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CHAPTER 1 


Overview 


This chapter provides a general description of FireWire support in the Mac OS, 
the driver architecture, and the system services that the Mac OS provides. 


1.1 Mac OS FireWire System Architecture 


The Mac OS provides a framework and a set of family services for FireWire 
driver software and the applications that control the drivers. The FireWire 
device family consists of all Macintosh PCI cards, and devices attached to the 
cards, that use a FireWire bus. 

The Mac OS provides a mechanism for loading driver software for FireWire 
family devices through the FireWire interface. It also provides a pluggable 
hardware abstraction layer (HAL) for FireWire cards, to isolate device driver 
software from their hardware specifics. The HAL architecture allows multiple 
FireWire cards from multiple vendors to work together in a single system. 


1.2 FireWire Drivers 


The FireWire driver architecture follows the conventions laid out in the 
document Designing PCI Cards and Drivers for Power Macintosh Computers 
(available through the Apple Developer Catalog). While this document 
pertains to PCI drivers, most of its content is not PCI-specific and relates to all 
driver architectures. 

As described in Designing PCI Cards and Drivers, all FireWire drivers have a 
driver descriptor record that is used when loading the driver. This driver 
descriptor record contains a string that is used to match the driver to an entry 
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in the Name Registry. Whenever a FireWire bus reset occurs, the FireWire 
driver loader expert scans the FireWire bus for all attached devices and creates 
an entry for each FireWire device, using the device's Spec_Id and Sw_Versi on 
values to generate the Name Registry entry name. The FireWire driver loader 
expert then issues a notification event that a new device has been attached. The 
appropriate driver loader expert receives the notification and loads and 
instantiates the correct driver for the new device. When a disk drive is 
attached, for example, the block storage driver loader expert receives 
notification. It loads and instantiates a block storage driver and notifies the 
Finder to mount the disk drive volume. 

Once a driver has been loaded and instantiated by a driver loader expert, it 
registers itself with the FireWire driver family. In the registration call, the driver 
can specify a pointer to its private data records, which it uses when it is called 
by the FireWire services. The registration call returns the driver's reference ID 
and a CSR configuration ROM entry ID for the device's CSR unit directory. 
These IDs are further detailed below. 


1.3 FireWire Interface Modules 


The FireWire family services provide an architecture for pluggable HALs. This 
architecture, called the FireWire Interface Module (FWIM) architecture, 
abstracts the particulars of FireWire cards from the drivers that control devices 
connected to the cards. The FWIM architecture also allows multiple cards from 
multiple vendors to work together in a single system. The FireWire services 
keep track of which FWIM each driver needs to communicate through. The 
FWIM architecture borrows from the SCSI interface module (SIM) architecture, 
which also allows multiple SCSI cards from multiple vendors to work together 
in a single system. 

Each FWIM is a driver written according to Designing PCI Cards and Drivers. It 
has a driver descriptor that is used to match it with a FireWire card. The 
FireWire services scan the Name Registry for devices that have a driver with a 
service category of ’fwi m'. The pertinent driver information should have already 
been placed in the Name Registry by the device tree boot code. The expert 
loads the FWIM fragment and calls an initialization routine. It then uses the 
FWIM interface to scan the bus for all FireWire devices and cause their 
respective drivers to be loaded, as described in Section 1.2. 
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1.4 Asynchronous Services 


The FireWire driver family services support sending asynchronous requests to 
remote nodes on the FireWire bus. Basic read, write, and lock requests are 
supported. In addition, atomic request routines are provided for common 
atomic operations such as bitwise logical operations, addition, and 
incrementing. 

FireWire reference IDs are central to the FireWire driver architecture, 
particularly to the asynchronous request services. These IDs reference various 
entities on the FireWire bus. They may reference drivers, devices, interface 
cards, the isochronous resource manager, the bus manager, or the root device. 
In addition, reference IDs of one type may be used to obtain reference IDs of 
another type. For example, a driver reference ID may be used to obtain the 
device reference ID for the device that the driver controls. The use of FireWire 
reference IDs greatly reduces the complexity of writing FireWire drivers. 
Typically, a driver uses its driver reference ID to specify the target (the device 
that the driver controls) of asynchronous requests. 

The use of the driver reference ID relieves the driver of having to deal with 
node IDs, topology generation numbers, and bus resets when sending an 
asynchronous request to the device it controls. Because the driver reference ID 
encapsulates all the addressing information for the driver's device, such as its 
unique ID and node ID, the asynchronous services can remap the target node 
ID and retry asynchronous requests when bus resets occur. 


1.5 Isochronous Services 


The FireWire driver family services support setting up and controlling 
isochronous data streams between multiple devices on the FireWire bus. These 
services can be used to set up an isochronous data stream between a remote 
device and the local node or between multiple remote devices. These services 
provide a flexible buffering mechanism to support a wide variety of 
isochronous data formats. 

Isochronous channel IDs are central to the isochronous services. These IDs are 
used when constructing an isochronous channel between multiple devices and 
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encapsulate all the information needed to manage the channel. By using these 
IDs, the construction and control of an isochronous channel may be 
coordinated between multiple drivers. 

The isochronous services allocate the required isochronous bandwidth and 
channel numbers and deal with the other requirements for isochronous data 
streams specified by IEEE Standard 1394. 

The isochronous services also coordinate the initialization and control of 
isochronous ports. The isochronous services use the term port to designate a 
device's connection to an isochronous channel. Typically, there are at least two 
ports involved in an isochronous channel, one for sending data and one for 
receiving the data. Each port is controlled by a driver, though a driver can 
control more than one port. When a user wishes to capture video from a 
FireWire camera, for example, the camera sends isochronous data from its 
isochronous port and the host system receives that data into its isochronous 
port. 


1.6 CSR Configuration ROM Services 


The FireWire driver family services support searching, creating, and accessing 
CSR configuration ROMs on the local and remote nodes of the FireWire bus. 
These services provide access to CSR configuration ROMs using relatively 
simple data structures, relieving the driver of having to interpret the format of 
the CSR configuration ROM directory hierarchy. 

CSR configuration ROM entry IDs are central to the CSR configuration ROM 
services. These IDs reference specific entries in the CSR configuration ROM and 
provide a convenient mechanism for working with them. For instance, when a 
driver registers with the FireWire services, it is given the entry ID for the CSR 
unit directory of the device it controls. If the driver needs to obtain information 
from its CSR unit directory, it may pass its unit directory entry ID to the CSR 
configuration ROM search routines to find its unit-specific information. Unit 
directory entry IDs are particularly useful when a FireWire device contains 
multiple units. 
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1.7 Function Control Protocol Services 


The FireWire driver family services support Function Control Protocol (FCP) 
commands. These services operate in a fashion similar to the asynchronous 
request services. They provide a mechanism that allows the driver to interpret 
and match FCP responses to oustanding FCP commands. 


1.8 Topology Services 


The FireWire driver family services help drivers obtain information about the 
FireWire bus topology. They provide the means to obtain the current bus 
topology map, a device's node ID, and a device's unique ID. 


1.9 Further Information 


To obtain further information about Apple FireWire technology, including 
information about participating in developer support and seeding programs, 
contact f i rewi re@appl e. com. 


1.7 Function Control Protocol Services 
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FireWire Client Architecture 


This chapter specifies the general characteristics of Mac OS FireWire clients and 
describes the calls they may receive from the Mac OS services. 


2.1 FireWire Client Framework 


The FireWire driver family provides for interfaces to different types of clients. 
These clients include regular drivers for FireWire peripheral devices and 
protocol drivers for peer-to-peer and networking interfaces. Typically, FireWire 
clients use FireWire services to perform asynchronous transactions and set up 
isochronous connections. FireWire clients may also receive various commands 
and notifications for similar services, in which case they register procedures 
that process these commands and notifications. This section describes the 
various client procedures that may be called by the FireWire services. 


2.2 Structures, Data Types, and Constants 


2.2.1 FWClientlnterfaceParams 


struct FWClientlnterfaceParamsStruct 


UI n 13 2 

FWReferencelD 
FWC1 ientComniandlD 
UI n 13 2 


interfaceSelector; 
fwReferencelD; 
fwCl ientComniandlD; 
fwClientSpecificData ; 


2.1 FireWire Client Framework 
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typedef struct 


FWC1 ientlnterfaceParamsStruct 

FWClientlnterfaceParams, 
*FWC1ientlnterfaceParamsPtr; 


interfaceSelector 

fwReferencel D 

fwClientCommandID 
fwClientSpeciftcData 


Selector indicating the type 

of operation being requested. 
Reference to client target 
of command. 

Reference to this command. 

Data for use by client. 


2.2.2 FWClientAsynchRequestParams 


struct FWCn entAsynch Request Pa rams Struct 


{ 

FWC1ientlnterfaceParams 

UInt32 

Ptr 

Ptr 

101 nt 16 
UI n 116 
UInt32 
UInt32 
UInt32 

FWAddressSpacelD 

Ptr 

} ; 

typedef struct FWC1ientAsynchReques 


fwClientlnterfaceParams 

generation 

receiveBuffer 
transmitBuffer 
sourcelD 
responseCode 
offset 


fwClientlnterfaceParams; 
generation; 
receiveBuffer; 
transmitBuffer; 
sourcelD; 
responseCode; 
offset; 

1ength ; 

extendedTCode; 
fwAddressSpacelD; 
pAddressSpecificData ; 

tStruct 

FWC1 i entAsynchRequestPa rams , 
FWC1ientAsynchRequestPa ramsPtr; 

Parameters common to all client 
requests. 

Bus generation during which 
request was received. 

Pointer to buffer of received data. 
Pointer to buffer of data to transmit. 
Source node ID of request. 

Response code to send. 

Offset into target address space. 
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1ength 

extendedTCode 

fwAddressSpacelD 
pAddressSpecificData 


Length of request. 

Extended transaction code for lock 
commands. 

ID of target address space. 

Client's private data for the address 
space. 


2.2.3 FWClientlsochPortParams 


struct FWClientlsochPortParamsStruct 
{ 

IsochChannelID isochChannelID; 

UInt32 refCon; 

Boolean portlsTalker; 

); 

typedef struct FWC1ientlsochPortParamsStruct 

FWClientlsochPortParams, 

*FWClientIsochPortParamsPtr; 

isochchannei id Reference to channel this port 

belongs to. 

refCon Reference constant specific to this port. 

portisTaiker If false, port is for listening; 

otherwise, port is for talking. 


2.2.4 FWClientlnitlsochPortParams 


struct FWClientlnitlsochPortParamsStruct 


FWClientlnterfaceParams 
FWClientlsochPortParams 
UI n 13 2 
UI n 13 2 

UI n 13 2 
Boolean 


fwCl ientlnterfaceParams; 
fwClientlsochPortParams; 
channelNum; 

supportedChannelNumHi, 
supportedChannelNumLo; 
speed; 
trial ; 


2.2 Structures, Data Types, and Constants 
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typedef struct 


FWClientlnitlsochPortParamsStruct 

FWClientlnitlsochPortParams, 

*FWClientInitIsochPortParamsPtr; 


fwClientInterfaceParams 

fwClientIsochPortParams 

channelNum 

supportedChannelNumHi, 
supportedChannelNumLo 

speed 

trial 


Parameters common to all client 
requests. 

Parameters common to all 

isochronous port requests. 

Requested channel number for 
isochronous port. 

Bits specifying the channel numbers 
that this isochronous port 
can currently support. 

Requested and supported speed of 
isochronous port. 

If true, request is only a trial 

to see what port parameters are 
supported. If false, request is 
the actual initialization of the 
isochronous port. 


2.2.5 FWClientReleaselsochPortParams 


struct FWC1ientReleaselsochPortParamsStruct 
{ 

FWClientlnterfaceParams fwCSientlnterfaceParams; 

FWClientlsochPortParams fwClientlsochPortParams; 

1 ; 

typedef struct FWC1ientReleaselsochPortParamsStruct 

FWClientReleaselsochPortParams, 

*FWC1ientRe1 easelsochPortParamsPtr; 

Parameters common to all client 
requests. 

Parameters common to all 

isochronous port requests. 


fwClientInterfaceParams 

fwClientIsochPortParams 
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2.2.6 FWClientlsochPortControlParams 


struct FWClientlsochPortControlParamsStruct 


FWClientlnterfaceParams 

FWClientlsochPortParams 

1 ; 

typedef struct FWC1ientlsochPortCon 


fwClientInterfaceParams 

fwClientIsochPortParams 


fwClientlnterfaceParams; 
fwClientlsochPortParams; 

.rolParamsStruct 

FWClientlsochPortControlParams, 

*FWClientIsochPortControlParamsPtr; 

Parameters common to all client 
requests. 

Parameters common to all 

isochronous port requests. 


2.2.7 FireWire Client Services Types 


typedef FWReferencelD 


FWC1ientID; 


typedef OSStatus 
FWC1ientlnte 
UInt32 

typedef FWClient 


(FWC1ientlnterfaceProc) ( 
rfaceParamsPtr pFWClientlnterfaceParams, 

*pCommandAcceptance); 

InterfaceProc *FWC1ientlnterfaceProcPtr; 


typedef OSStatus (FWC1ientReadProc) ( 

FWClientAsynchRequestParamsPtr pFWClientAsynchReques 

UInt32 *pCommandAcceptance); 

typedef FWC1ientReadProc *FWC1ientReadProcPtr; 


tParams, 


typedef OSStatus (FWC1ientWriteProc) ( 

FWClientAsynchRequestParamsPtr pFWClientAsynchRequestParams, 

UInt32 *pCommandAcceptance); 

typedef FWC1ientWriteProc *FWC1ientWriteProcPtr; 


typedef OSStatus (FWC1ientLockProc) ( 

FWClientAsynchRequestParamsPtr pFWClientAsynchRequestParams, 

UInt32 *pCommandAcceptance); 

typedef FWC1ientLockProc *FWC1ientLockProcPtr; 


2.2 Structures, Data Types, and Constants 
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typedef OSStatus (FWC1 ientlnitlsochPortProc) ( 

FWClientlnitlsochPortParamsPtr pFWClientlnitlsochPortParams, 

UInt32 *pCommandAcceptance); 

typedef FWClientlnitlsochPortProc *FWClientInitIsochPortProcPtr; 

typedef OSStatus (FWC1ientReleaselsochPortProc) ( 

FWC1ientRe1 easelsochPortParamsPtr pFWC1ientRelease IsochPortParams, 

UInt32 *pCommandAcceptance); 

typedef FWClientReleaselsochPortProc *FWClientRel ease IsochPortProcPtr; 

typedef OSStatus (FWC1ientStartlsochPortProc) ( 

FWClientlsochPortControlParamsPtr pFWClientlsochPortControlParams, 

UInt32 *pCommandAcceptance); 

typedef FWC1ientStartlsochPortProc *FWClientStartIsochPortProcPtr; 


typedef OSStatus (FWC1ientStopIsochPortProc) ( 

FWClientlsochPortControlParamsPtr pFWClientlsochPortControlParams, 


UInt32 

typedef FWClientStopIsochPortProc 
FWC1ientl D 

FWC1 ientlnterfaceProc 
FWC1ientlnterfaceProcPtr 
FWC1ientReadProc 

FWC1ientReadProcPtr 
FWC1ientWriteProc 

FWC1ientWriteProcPtr 
FWC1jentLockProc 

FWC1ientLockProcPtr 


*pCommandAcceptance); 
*FWClientStopIsochPortProcPtr; 

Reference to a FireWire client. 

Type of proc that will be called 
for generic client operations. 

Pointer to above proc. 

Type of proc that will be called 
to process read requests to 
address space owned by the client. 

Pointer to above proc. 

Type of proc that will be called 
to process write requests to 
address spaces owned by the client. 

Pointer to above proc. 

Type of proc that will be called 
to process lock requests to 
address spaces owned by the client. 

Pointer to above proc. 
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FWClientlnitlsochPortProc Type of proc that will be called 

to initialize an isochronous 
port owned by the client. 

FWClientlnitlsochPortProcPtr Pointer to above proc. 

FWC1 ientRel easelsochPortProc Type of proc that will be called to 

release an isochronous port owned 
by the client. 

FWC1 i entRel easelsochPortProc Pointer to above proc. 

FWClientStartlsochPortProc Type of proc that will be called to 

start an isochronous port owned by 
the client. 

FWC1 ientStartlsochPortProcPtr Pointer to above proc. 

FWC1 i entStopIsochPortProc Type of proc that will be called to 

stop an isochronous port owned by 
the client. 

FWC1 i entStopIsochPortProcPtr Pointer to above proc. 

2.2.8 FireWire Client and Services Constants 

enum 

i 

klnvalidFWClientID = klnvalidFWReferencelD 

); 

klnvat idFWCt ientID If a client ID is equal to this constant, it 

is invalid. 

enum 

i 

kFWClientCommandAcceptNoMore = 0, 

kFWClientCommandAcceptMore = 1, 

kFWClientCommandRejected = 2 

); 

kFWCl i entCommandAcceptNoMore This constant specifies that the 

given command has been accepted 
but no more can be accepted. 


2.2 Structures, Data Types, and Constants 


27 



CHAPTER 2 


FireWire Client Architecture 


kFWCl i entCommandAcceptMore This constant specifies that the 

given command has been accepted 
and more commands can be 
accepted. 

kFWCl i entCommandRejected This constant specifies that the 

given command has been rejected 
but the command may later be 
retried. 


2.3 FireWire Client Services 


2.3.1 FWSetFWClientResetNotifyProc 

FWSetFWCl i entResetNoti fyProc specifies the procedure to be called when a bus 
reset occurs. 


OSStatus FWSetFWClientResetNotifyProc ( 

FWReferencelD fwReferencelD, 

FWClientResetNotifyProcPtr ResetNotifyProc); 


--> fwReferencelD Reference to client to set reset 

notification proc for. 

--> fwCl i entResetNoti fyProc Procedure that will be called when 

a bus reset occurs. 


DESCRIPTION 

FWSetFWCl t entResetNoti fyProc specifies the procedure to be called when a bus 
reset occurs. This procedure will be called after the FireWire services have 
scanned all the devices on the bus but before the various bus management 
functions have been performed. Clients that need to access their devices within 
a short time period after a bus reset should use FWSetFWCl f entResetNoti fyProc 
to register for reset notification. Otherwise, clients requiring reset notification 
should use FWSetFWCl i entBusManagementNoti fyProc. A client may call both 
FWSetFWCl ientResetNotifyProc and FWSetFWCl i entBusManagementNotifyProc to 
receive notification at both times. 


28 


2.3 FireWire Client Services 



CHAPTER 2 


FireWire Client Architecture 

2.3.2 FWGetFWClientResetNotifyProc 


FWGetFWCl i entResetNoti fy Proc returns the procedure to be called when a bus 
reset occurs. 


OSStatus 


FWGetFWClientResetNotifyProc ( 


FWReferencelD 

FWClientResetNotifyProcPtr 


fwReferencelD, 

*pFWClientResetNotifyProc) 


- -> fwReferencelD Reference to client to get reset 

notification proc for. 

--> pFWCl i entResetNoti fyProc Returned procedure that will be 

called when a bus reset occurs. 


DESCRIPTION 

FWGetFWCl i entResetNoti fyProc returns the procedure set by the last call to 
FWSetFWCl i entResetNoti fyProc. 


2.3.3 FWSetFWClientBusManagementNotifyProc 

FWSetFWCl i entBusManagementNoti fyProc specifies the procedure to be called 
after all bus managment functions have been performed following a bus reset, 


OSStatus FWSetFWClientBusMan 

FWReferencelD 

FWClientResetNotifyProcPtr 
--> fwReferencelD 

--> fwClientResetNotifyProc 


agementNotifyProc ( 
fwReferencelD, 
fwClientResetNotifyProc); 

Reference to client to set bus 

management notification proc for. 

Procedure that will be called once 
all of the bus management 
functions have been performed. 


DESCRIPTION 

FWSetFWCl i entResetNoti fyProc specifies the procedure to be called once all of 
the bus managment functions have been performed after a bus reset. This 
routine is similar to FWSetFWCl i entResetNoti fyProc except that notification 


2.3 FireWire Client Services 
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occurs later. Unless a client must access its device within a short time after a 

bus reset, it should register for reset notification by using 

FWSetFWCl i entBusManagementNoti fyProc. Doing so will give the FireWire 

services more processing cycles to perform the necessary bus management 

functions. 


2.3.4 FWGetFWClientBusManagementNotifyProc 

FWGetFWCl i entBusManagementNoti fyProc returns the procedure to be called once 
all of the bus managment functions have been performed after a bus reset. 


OSStatus FWGetFWClientBusMan 

FWReferencelD 

FWC1ientResetNotifyProcPtr 
--> fwReferencelD 

--> pFWClientResetNotifyProc 


gementNotifyProc 
fwReferencelD, 

*pFWClientResetNotifyProc); 

Reference to client to get bus 

management notification proc for. 

Returned procedure that will be 
called once all of the bus 
management functions have been 
performed. 


DESCRIPTION 

FWGetFWCl i entBusManagementNoti fyProc returns the procedure set by the last call 
to FWSetFWClientBusManagementNotifyProc. 


2.3.5 FWSetFWClientReadRequestProc 

FWSetFWCl i entReadReqeustProc specifies the procedure to be called when a 
remote node sends a read request to an address space allocated by the client. 


OSStatus 


FWSetFWClientReadRequestProc ( 


FWReferencelD 
FWClientReadProcPtr 


fwReferencelD, 
fwClientReadProc); 


--> fwReferencelD Reference to client to set the read 

request proc for. 

--> fwCl i entReadProc Procedure that will be called when 

a read request is received. 
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DESCRIPTION 

FWSetFWCl i entReadRequestProc specifies the procedure to be called when a 
remote node sends a read request to an address space allocated by the client. 
This procedure will be called before a response is sent for the read request. 


2.3.6 FWGetFWClientReadRequestProc 

FWGetFWCl i entReadRequestProc returns the procedure to be called when a 
remote node sends a read request to an address space allocated by the client. 

OSStatus FWGetFWClientReadRequestProc ( 

FWReferencelD fwReferencelD, 

FWClientReadProcPtr *pFWClientReadProc); 


--> 

fwReferencelD 

Reference to client to get the read 
request proc for 

--> 

pFWClientReadProc 

Returned procedure that will be 
called when a read request is 


received. 


DESCRIPTION 

FWGetFWCl i entReadRequestProc returns the procedure set by the last call to 
FWSetFWCl ientReadRequestProc. 


2.3.7 FWSetFWClientReadCompleteProc 

FWSetFWCl i entReadCompl eteProc specifies the procedure to be called when a 
read response has been sent to a remote node that sent a read request to an 
address space allocated by the client. 


OSStatus 


FWSetFWClientReadCompleteProc ( 


FWReferencelD 

FWClientReadProcPtr 

--> fwReferencelD 

--> fwClientReadProc 


fwReferencelD, 
fwClientReadProc); 

Reference to client to set the read 
complete proc for. 

Procedure that will be called when 
a read response has been sent. 


2.3 FireWire Client Services 
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DESCRIPTION 

FWSetFWCl i entReadCompl eteProc specifies the procedure to be called when a 
read response has been sent to a remote node that sent a read request to an 
address space allocated by the client. 


2.3.8 FWGetFWClientReadCompleteProc 

FWGetFWCl i entReadCompl eteProc returns the procedure to be called when a read 
response has been sent to a remote node that sent a read request to an address 
space allocated by the client. 


OSStatus 


FWGetFWClientReadCompleteProc ( 


FWReferencelD 
FWClientReadProcPtr 

fwReferencelD 

pFWClientReadProc 


fwReferencelD 
*pFWClientReadProc); 

Reference to client to get the 
read complete proc for. 

Returned procedure that will be 

called when a read response has 
been sent. 


DESCRIPTION 

FWGetFWCl f entReadCompl eteProc returns the procedure set by the last call to 

FWSetFWClfentReadCompl eteProc. 


2.3.9 FWSetFWClientWriteRequestProc 

FWSetFWCl i entWri teRequestProc specifies the procedure to be called when a 
remote node sends a write request to an address space allocated by the client. 


OSStatus 


FWSetFWClientWriteRequestProc ( 


FWReferencelD 

FWC1ientWriteProcPtr 


fwReferencelD, 
fwClientWriteProc); 


--> fwReferencelD Reference to client to set the 

write request proc for. 

--> fwCl i entWri teProc Procedure that will be called when 

a write request is received. 
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DESCRIPTION 

FWSetFWCl i entWri teRequestProc specifies the procedure to be called when a 
remote node sends a write request to an address space allocated by the client. 
This procedure will be called only if an ack_pendi ng was sent for the received 
request packet and will be called before the response packet is sent. 


2.3.10 FWGetFWClientWriteRequestProc 

FWGetFWCl i entWri teRequestProc returns the procedure to be called when a 
remote node sends a write request to an address space allocated by the client. 

OSStatus FWGetFWClientWriteRequestProc ( 

FWReferencelD fwReferencelD, 

FWClientWriteProcPtr *pFWClientWriteProc); 


--> 

fwReferencelD 

Reference to client to get the 



write request proc for. 

--> 

pFWClientWriteProc 

Returned procedure that will be called 


when a write request is received. 

DESCRIPTION 

FWGetFWCl i entWri teRequestProc returns the procedure set by the last call to 
FWSetFWClientWriteRequestProc. 


2.3.11 FWSetFWClientWriteCompleteProc 

FWSetFWCl i entWri teCompl eteProc specifies the procedure to be called when a 
write response or ack_compl ete has been sent to a remote node that sent a write 
request to an address space allocated by the client. 

OSStatus FWSetFWClientWriteCompleteProc ( 

FWReferencelD fwReferencelD 

FWClientWriteProcPtr fwClientWriteProc); 


--> 

fwReferencelD 

Reference to client to set the 



write complete proc for. 

--> 

fwClientWriteProc 

Procedure that will be called when 


a write response or ack_compl ete 
has been sent. 
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DESCRIPTION 

FWSetFWCl f entWri teCompl eteProc specifies the procedure to be called when a 
write response or ack_compl ete has been sent to a remote node that sent a write 
request to an address space allocated by the client. 


2.3.12 FWGetFWClientWriteCompleteProc 

FWGetFWCl i entWri teCompl eteProc returns the procedure to be called when a 
write response or ack_compl ete has been sent to a remote node that sent a write 
request to an address space allocated by the client. 


OSStatus FWGetFWClientWrite 

FWReferencelD 
FWC1ientWriteProcPtr 

--> fwReferencel D 

--> pFWClientWriteProc 


ompleteProc ( 

fwReferencelD, 

*pFWClientWriteProc); 

Reference to client to get the write 
complete proc for. 

Returned procedure that will be 
called when a write response or 
ack_compl ete has been sent. 


DESCRIPTION 

FWGetFWCl i entWri teCompl eteProc returns the procedure set by the last call to 
FWSetFWClIentWriteCompl eteProc. 


2.3.13 FWSetFWClientLockRequestProc 

FWSetFWCl i entLockRequestProc specifies the procedure to be called when a 
remote node sends a lock request to an address space allocated by the client 


OSStatus 


FWSetFWClientLockRequestProc ( 


FWReferencelD 
FWClientLockProcPtr 


fwReferencelD, 

ClientLockProc); 


--> fwReferencelD Reference to client to set the lock 

request proc for. 

--> fwCl i entLockProc Procedure that will be called when 

a lock request is received. 
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DESCRIPTION 

FWSetFWCl i entLockRequestProc specifies the procedure to be called when a 
remote node sends a lock request to an address space allocated by the client. 
This procedure will be called before a response is sent for the lock request. 


2.3.14 FWGetFWClientLockRequestProc 

FWGetFWCl i entLockRequestProc returns the procedure to be called when a 
remote node sends a lock request to an address space allocated by the client. 

OSStatus FWGetFWClientLockRequestProc ( 

FWReferencelD fwReferencelD, 

FWClientLockProcPtr *pFWClientLockProc); 


--> 

fwReferencelD 

Reference to client to get the 
lockrequest proc for. 

--> 

pFWClientLockProc 

Returned procedure that will be 
called when a lock request is 


received. 


DESCRIPTION 

FWGetFWCl i entLockRequestProc returns the procedure set by the last call to 
FWSetFWClientLockRequestProc . 


2.3.15 FWSetFWClientLockCompleteProc 

FWSetFWCl i entLockCompl eteProc specifies the procedure to be called when a lock 
response has been sent to a remote node that sent a lock request to an address 
space allocated by the client. 


OSStatus 


FWSetFWClientLockCompleteProc ( 


FWReferencelD 

FWClientReadProcPtr 


fwReferencelD, 
fwClientReadProc) 


--> fwReferencelD Reference to client to set the 

lock complete proc for. 

--> fwCl i entReadProc Procedure that will be called 

when a lock response has been 
sent. 
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DESCRIPTION 

FWSetFWCl f entLockCompl eteProc specifies the procedure to be called when a lock 
response has been sent to a remote node that sent a lock request to an address 
space allocated by the client. 


2.3.16 FWGetFWClientLockCompleteProc 

FWGetFWCl i entLockCompl eteProc returns the procedure to be called when a lock 
response has been sent to a remote node that sent a lock request to an address 
space allocated by the client. 


OSStatus 


FWGetFWClientLockCompleteProc ( 


FWReferencelD 
FWClientReadProcPtr 

fwReferencelD 

pFWClientReadProc 


fwReferencelD, 

*pFWClientReadProc); 

Reference to client to get the 
lock complete proc for. 

Returned procedure that will be 
called when a lock response has 
been sent. 


DESCRIPTION 

FWGetFWCl i entLockCompl eteProc returns the procedure set by the last call to 

FWSetFWCl}entLockCompl eteProc. 


2.3.17 FWSetFWClientlnitlsochPortProc 

FWSetFWCl i entlni tlsochPortProc specifies the procedure to be called to 
initialize an isochronous port controlled by a client. 


OSStatus FWSetFWClientlnitlsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientlnitlsochPortProcPtr fwClientlnitlsochPortProc); 


--> fwReferencelD Reference to client to set the 

init isoch port proc for. 

--> fwCl i entlni tlsochPortProc Procedure that will be called to 

initialize an isochronous port. 
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DESCRIPTION 

FWSetFWClientlnitlsochPortProc specifies the procedure to be called to initialize an 
isochronous port controlled by a client. 


2.3.18 FWGetFWClientlnitlsochPortProc 

FWGetFWClientlnitlsochPortProc returns the procedure to be called to initialize 
an isochronous port controlled by a client 


OSStatus FWGetFWClientlnitlsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientlnitlsochPortProcPtr *pFWClient!nitIsochPortProc); 


> fwReferencelD 

> pFWClientlnitlsochPortProc 


Reference to client to get the 
init isoch port proc for. 

Returned procedure that will be 
called to initialize an 
isochronous port. 


DESCRIPTION 

FWGetFWCl i entlni tlsochPortProc returns the procedure set by the last call to 
FWSetFWClientlnitlsochPortProc. 


2.3.19 FWSetFWClientReleaselsochPortProc 

FWSetFWCl ientRel easelsochPortProc specifies the procedure to be called to 
release all resources allocated for an isochronous port controlled by a client. 


OSStatus FWSetFWClientReleaselsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientReleaselsochPortProcPtr fwClientReleaselsochPortProc); 


> fwReferencelD 

> fwClientReleaselsochPortProc 


Reference to client to set the 
release isoch port proc for. 
Procedure that will be called to 
release an isochronous port. 


2.3 FireWire Client Services 


37 



CHAPTER 2 


FireWire Client Architecture 


DESCRIPTION 

FWSetFWCl f entRel easelsochPortProc specifies the procedure to be called to 
release all resources allocated for an isochronous port controlled by a client. 


2.3.20 FWGetFWClientReleaselsochPortProc 

FWGetFWCl i entRel easelsochPortProc returns the procedure to be called to 
release all resources allocated for an isochronous port controlled by a client. 


OSStatus FWGetFWClientReleaselsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientReleaselsochPortProcPtr *pFWClientReleaselsochPortProc); 


> fwReferencelD 

> pFWClientlnitlsochPortProc 


Reference to client to get the 
release isoch port proc for. 

Returned procedure that will be 
called to release an 
isochronous port. 


DESCRIPTION 

FWGetFWCl i entRel easelsochPortProc returns the procedure set by the last call to 
FWSetFWCl ientReleaselsochPortProc. 


2.3.21 FWSetFWClientStartlsochPortProc 

FWSetFWCl i entStartlsochPortProc specifies the procedure to be called to start 
an isochronous port controlled by a client. 


OSStatus FWSetFWClientStartlsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientStartlsochPortProcPtr fwClientStartlsochPortProc); 


> fwReferencelD 

> fwClientStartlsochPortProc 


Reference to client to set the 
start isoch port proc for. 
Procedure that will be called to 
start an isochronous port. 
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DESCRIPTION 

FWSetFWCl ientStartlsochPortProc specifies the procedure to be called to start 
an isochronous port controlled by a client. 


2.3.22 FWGetFWClientStartlsochPortProc 

FWGetFWCl ientStartlsochPortProc returns the procedure to be called to start an 
isochronous port controlled by a client. 


OSStatus FWGetFWClientStartlsochPortProc ( 

FWReferencelD fwReferencelD, 

FWClientStartlsochPortProcPtr *pFWClientStartlsochPortProc); 


> fwReferencelD 

> pFWClientStartlsochPortProc 


Reference to client to get the 
start isoch port proc for. 

Returned procedure that will be 
called to start an 
isochronous port. 


DESCRIPTION 

FWGetFWCl ientStartlsochPortProc returns the procedure set by the last call to 
FWSetFWClientStartlsochPortProc. 


2.3.23 FWSetFWClientStopIsochPortProc 

FWSetFWCl ientStopIsochPortProc specifies the procedure to be called to stop an 
isochronous port controlled by a client 


OSStatus FWSetFWClientStopI 

FWReferencelD 

FWC1ientStopIsochPortProcPtr 
--> fwReferencelD 

--> fwClientStopIsochPortProc 


ochPortProc ( 

fwReferencelD 

fwClientStopIsochPortProc); 

Reference to client to set the 
stop isoch port proc for. 
Procedure that will be called to 
stop an isochronous port. 
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DESCRIPTION 

FWSetFWCl |entStopIsochPortProc specifies the procedure to be called to stop an 
isochronous port controlled by a client. 


2.3.24 FWGetFWClientStopIsochPortProc 

FWGetFWCl i entStopIsochPortProc returns the procedure to be called to stop an 
isochronous port controlled by a client. 


OSStatus FWGetFWClientStopIsochPortProc ( 


FWReferencelD 

FWClientStopIsochPortProcPtr 
--> fwReferencel D 

--> pFWCl ientStopIsochPortProc 


fwReferencelD, 

*pFWClientStopIsochPortProc); 

Reference to client to get the 
stop isoch port proc for. 

Returned procedure that will be 
called to stop an isochronous 
port. 


DESCRIPTION 

FWGetFWCl f entStopIsochPortProc returns the procedure set by the last call to 
FWSetFWClientStopIsochPortProc. 


2.3.25 FWClientCommandlsComplete 

When a FireWire client has completed a command sent to one of its interface 
procedures, it calls FWC1 i entCommandlsCompl ete to notify the FireWire services 
that the command has been completed. 

OSStatus FWClientCommandlsComplete ( 

FWC1ientCommandID fwClientCommandID 

OSStatus commandStatus); 

--> fwCl ientCommandID Reference to completed command. 

This should be set to the 

fwCl i entCommandID field in the 
FWC1 i entlnterfaceParams passed in 
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to the client's interface 
procedure. 

- -> commandStatus Final status of command. 


DESCRIPTION 

When a FireWire client is finished executing a command sent to one of its 
interface procedures, it notifies the FireWire services by calling 
FWC1 i entCommandlsCompl ete. The client specifies the completed command with 
fwCl i entCommand ID, which was passed to the client when the FireWire services 
called the client's interface procedure. The client indicates the final status of the 
command in commandStatus. The client may call FWC1 i entCommandlsCompl ete in 
any environment except primary interrupt level. 


2.4 FireWire Client Interface Procedures 


2.4.1 FWClientlnterfaceProc 

FireWire clients can provide various interface procedures to receive calls from 
the FireWire services for purposes such as managing isochronous data streams 
or processing asynchronous requests sent by remote devices. 


typedef OSStatus (FWC1ientInterf 

FWClientlnterfaceParamsPtr 

UInt32 

<--> pFWClientlnterfaceParams 
--> fwClientCommandID 


--> fwClientSpecificData 


<-- pCommandAcceptance 


iceProc) ( 

pFWClientlnterfaceParams, 
*pCommandAcceptance); 

Pointer to parameter block. 

Reference to this command. 

This is used in calls to 
FWC1ientCommandlsComplete. 
Client's private data. This is 

the same data that the client 
passed into its registration call 
Value returned specifying acceptance 
of current and future commands. 
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DESCRIPTION 

The FireWire client interface procedures are called by the FireWire services to 
send commands to the client. The procedures are used for a variety of 
purposes, such as managing isochronous data streams and processing 
asynchronous requests sent by remote devices. Typically, the interface 
parameters are not of the generic type described earlier but have additional 
parameters that further specify the operation being requested. The various 
types of commands are detailed below. 

FWC1 i entlnterfaceProc is the generic version of the command procedures 
described below. The fwCl i entCommandID is used as a reference to the command 
being issued to the client. Clients use the fwCl i entCommand ID to tell the FireWire 
services that the issued command has been completed by passing it in to a call 

to FWC1ientCommandlsComplete. 

When the FireWire services issue a command to the client, 

FWCli entlnterfaceProc does not need to complete the command before 
returning to the FireWire services. This allows for asynchronous operation of 
the various client commands. When the issued command has been completed, 
the client must call FWC1 i entCommand I sCompl ete. 

Unless a client command is specified as only running at task level, the 
command may not use any services that cannot run at nontask level. This 
includes most resource allocation services and all synchronous services. Thus, a 

call to FWC1 ientStartlsochPortProc may not issue a synchronous FWWrite 
command; the FWWri te command must be used asynchronously. 

The client sets the pCommandAcceptance parameter when it receives a command 

from the FireWire services. If the client sets this parameter to 

kFWCl i entCommandAcceptNoMore, it indicates that it can process the given 

command but cannot process any more until it completes a command by 

calling FWC1 i entCommand I sCompl ete. If the client sets the parameter to 

kFWCl i entCommandAcceptMore, it indicates that it can process the given command 

and can process more commands. If the client sets the parameter to 

kFWCl i entCommandRejected, it indicates that it cannot process the command now 

but may be able to after it completes a command by calling 

FWC1ientCommandlsComplete. 

This mechanism allows a client to process more than one command at a time. If 
a client is not processing a command, it should not return 

kFWCl i entCommandRejected when given a new command. 

While a client may have multiple oustanding commands at one time, the 
FireWire services will ensure that calls made to the client are serialized. Thus, 
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when one of the client interface procedures is called, no more calls will be 
made to the client until the first call returns (either completed or not 
completed). In addition, FWCommandCompl eti onProcs will all be serialized with 
respect to each other and the client interface procedures. However, calls to 
different clients may not necessarily be serialized with respect to each other. 


2.4.2 FWClientResetNotifyProc 

When a FireWire bus reset occurs, the FireWire services sends notification to 
the client through the client's FWC1 i entResetNoti fyProc interface procedure. 


typedef OSStatus (FWClientResetNotifyProc) ( 


FWClientlnterfaceParamsPtr 
UI n 13 2 

<--> pFWClientlnterfaceParams 

<-- pCommandAcceptance 


pFWClientlnterfaceParams, 
*pCommandAcceptance); 

Pointer to parameter block. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

When a FireWire bus reset occurs, a FireWire client may receive notification 
through its FWCli entResetNoti fyProc interface procedure. The client may take 
any action it needs to in response to this notification. A client may request to 
receive reset notification either before or after the bus management functions 
have been performed. 

This procedure may be called in any environment except primary interrupt 
level. 


2.4.3. FWClientReadProc 

When a remote node accesses a client allocated address space with a read 
request, the FireWire services sends notification to the client through the 
client's FWClientReadProc interface procedure. 

typedef OSStatus (FWClientReadProc) ( 

FWClientAsynchRequestParamsPtr pFWClientAsynchRequestPa rams, 

UInt32 *pCommandAcceptance); 
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<--> pFWClientAsynchRequestPa rams 
--> generation 

--> transmitBuffer 
--> sourcelD 

--> responseCode 

--> offset 

--> length 

--> extendedTCode 

--> fwAddressSpacelD 

--> pAddressSpecificData 

<-- pCommandAcceptance 


Pointer to parameter block. 

Bus generation value during 
which request was received 

Pointer to buffer of data to send. 

Source node ID of request. 

Response code to send. 

Offset into target address space. 

Length of request. 

Extended transaction code for 
request 

ID of target address space. 

Client's private data for the 
address space. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

When a remote node sends a read request targeted to a local address space, the 
client of the address space may receive notification of the request before and 
after the read response is sent. 

If the client specified a backing store for the address space, the FireWire 
services will send a read response back to the remote node, using the backing 
store; this data will be contained in transmi tBuffer. If the client allocated its 
address space specifying kFWAddressReadRequestNoti fy, the contents of 
transmi tBuffer can be modified by the client before it is sent to the remote 
node. 

If the client did not specify a backing store, it must place the appropriate data 
in transmi tBuffer. In this case, the client must specify 
kFWAddressReadRequestNoti fy when allocating the address space. 

When the client returns from the call to its interface procedure, the read 
response will be sent to the remote node with the data contained in 
transmi tBuffer. If the client specified kFWAddressReadCompl eteNoti fy when 
allocating the address space, it will be called again if the read response was 
successfully delivered. The response code sent in the response will equal the 
value of responseCode. The value of responseCode is set by the FireWire services 
and may be modified by the client before the response is sent. 
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This interface procedure will be called only if the client requested read request 
or complete notification when it allocated the address space. 

This procedure may be called in any environment except primary interrupt 
level. 


2.4.4. FWClientWriteProc 


When a remote node accesses a client allocated address space with a write 
request, the FireWire services sends notification to the client through the 
client's FWClientWriteProc interface procedure. 

typedef 

OSStatus (FWClientWriteProc) 

( 

FWClientAsynchRequestParamsPtr 

pFWClientAsynchRequest Pa rams, 

UInt32 

*pCommandAcceptance); 

<--> 

pFWClientAsynchRequestParams 

Pointer to parameter block. 

--> 

generation 

Bus generation value during 



which request was received. 

--> 

receiveBuffer 

Pointer to buffer of received data. 

--> 

sourcelD 

Source node ID of request. 

--> 

responseCode 

Response code to send. 

--> 

offset 

Offset into target address space. 

--> 

1ength 

Length of request. 

--> 

extendedTCode 

Extended transaction code 



for request. 

--> 

fwAddressSpacelD 

ID of target address space. 

--> 

pAddressSpecificData 

Client's private data for 



the address space. 

<-- 

pCommandAcceptanee 

Value returned specifying 


acceptance of current and 
future commands. 


DESCRIPTION 

When a remote node sends a write request targeted at a local address space, the 
client of the address space may receive notification of the request before and 
after completion of the transaction. 

If the client specified a backing store for the address space, the FireWire 
services will update the backing store buffer with the data sent from the remote 
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node; this data will be contained in recei veBuf fer. If the client allocated its 
address space specifying kFWAddressWri teRequestNoti fy, the contents of 
recei veBuffer can be modified by the client before it is written into the backing 
store buffer. The backing store buffer will only be written to if an ack_compl ete 
or a write response packet is successfully delivered to the requesting node. If 
the client did not specify a backing store, is should specify 
kFWAddressWri teCompl eteNoti fy when allocating the address space. 

If the client specified kFWAddressWri teCompl eteNoti fy when allocating the 
address space, if will be called if an ack_compl ete or a write response packet is 
successfully delivered to the requesting node. The client should ensure that the 
write request will have no effect if an ack_compl ete or a write response packet 
could not be successfully delivered to the requesting node. Thus, any actions 
performed by the client as a result of receiving the write request should not 
occur until the client's FWC1 i entWri teCompl eteProc is called. If a write response 
packet is to be sent, the write response code will be set to the value of 
responseCode. This value is set by the FireWire services. If the client specified 
kFWAddressWri teRequestNoti fy when allocating the address space, FireWire 
may alter the value in responseCode before the write response is sent. 

This interface procedure will be called only if the client requested write request 
or complete notification when it allocated the address space. It may be called in 
any environment except primary interrupt level. 


2.4.5. FWClientLockProc 

When a remote node accesses a client allocated address space with a lock 
request, the FireWire services sends notification to the client through the 
client's FWC1 i entLockProc interface procedure. 


typedef OSStatus (FWClientLockProc) ( 

FWC1ientAsynchRequestPa ramsPtr pFWClientAsynchRequestPa rams, 

UInt32 *pCommandAcceptance); 


<--> pFWClientAsynchRequestPa rams 
--> generation 

--> receiveBuffer 

--> transmitBuffer 

--> sourcelD 

--> responseCode 

--> offset 


Pointer to parameter block. 

Bus generation value during 
which request was received. 
Pointer to buffer of received data. 
Pointer to buffer of data to send. 
Source node ID of request. 
Response code to send. 

Offset into target address space. 
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--> length 

--> extendedTCode 

--> fwAddressSpacelD 

--> pAddressSpecificData 

<-- pCommandAcceptance 


Length of request. 

Extended transaction code for 
request. 

ID of target address space. 

Client's private data for the 
address space. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

When a remote node sends a lock request targeted at a local address space, the 
client of the address space may receive notification of the request before and 
after completion of the transaction. 

If the client specified a backing store for the address space, the FireWire 
services will apply the lock to the buffer with the data sent from the remote 
node. The received lock request data will be contained in recei veBuf fer. The 
lock response data to be sent to the remote node will be contained in 
transmi tBuffer. If the client allocated its address space specifying 
kFWAddress LockRequestNoti fy, the contents of transmi tBuf fer can be modified 
by the client before it is written into the backing store buffer. The backing store 
buffer will only be updated if a lock response packet is successfully delivered 
to the requesting node. If the client did not specify a backing store, is should 
specify kFWAddress LockRequestNoti fy and kFWAddressLockCompl eteNoti fy when 
allocating the address space. 

If the client specified kFWAddressLockCompl eteNoti fy when allocating the 
address space, it will be called if a lock response packet is successfully 
delivered to the requesting node. The client should ensure that the lock request 
will have no effect if a lock response packet could not be successfully delivered 
to the requesting node. Thus, any actions performed by the client as a result of 
receiving the lock request should not occur until the client's 
FWC1 i entLockCompl eteProc is called. The response code sent in the response will 
equal the value of responseCode. The value of responseCode is set by the 
FireWire services and may be modified by the client before the response is sent. 

This interface procedure will be called only if the client requested lock request 
or complete notification when it allocated the address space. 

This procedure may be called in any environment except primary interrupt 
level. 
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2.4.6. FWClientlnitlsochPortProc 

When the FireWire services library is asked to initialize an isochronous channel 
for operation, FWC1 i entlni tlsochPortProc calls each client of the channel to 
initialize its isochronous port in the channel. 


typedef OSStatus (FWClientlni 

FWClientlnitlsochPortParamsPtr 
UInt32 

<--> pFWClientlnitlsochPortParams 
--> refCon 

--> portlsTalker 

--> channelNum 

<-- supportedChannel NumFli , 

supportedChannelNumLo 

<--> speed 

- - > trial 

<-- pCommandAcceptance 


tlsochPortProc) ( 

pFWClientlnitlsochPortParams, 
*pCommandAcceptance); 

Pointer to parameter block. 
Reference constant specific 
to this port. 

If false, port is for 

listening; otherwise, port 
is for talking. 

Requested channel number for 
isochronous port. 

Bits specifying the channel 
numbers this isochronous 
port can currently support. 
Requested and supported 

speed of isochronous port 
If true, request is only a 
trial to see what port 
parameters are supported. 

If fal se, request is the actual 
initialization of the 
isochronous port. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

When an isochronous channel is being initialized, each client of the channel is 
called through its FWClientlnitlsochPortProc interface procedure to initialize 
its port in the channel. 

The client interface procedure is called twice by the FireWire services. The first 
call is a trial to establish what parameters each port can support; this trial is 
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called with the tri al parameter set to true. During this trial phase, the client 
should return the parameters supported by its port. All the supported channel 
numbers should be specified in the appropriate bit fields in 
supportedChannel NumHi and supportedChannel NumLo; a 1 in bit position n (bit 0 
being the most significant bit of supportedChannel NumberHi ) of the 64-bit value 
of supportedChannel NumHi and supportedChannel NumLo indicates that channel 
number n is supported. For example, if supportedChannel NumLo is equal to 3, 
channel numbers 62 and 63 are supported. The maximum speed supported by 
the port should be returned in the speed field. 

The FireWire services call each client to determine what common set of 
parameters is supported by all isochronous ports. If a common set of 
parameters is not supported by all ports, the channel initialization fails. 

If a common set of parameters is supported by all ports, the FireWire services 
call the client interface procedure again to do the real port initialization; in this 
call, the tri al parameter is set to fal se. Each client should do whatever it 
needs to prepare its port for operation with the given parameters. Any error 
condition returned from this second call will cause channel initialization to fail. 

This procedure is called only at task level. 


2.4.7. FWClientReleaselsochPortProc 

When the FireWire services library is asked to release an isochronous channel, 
FWC1 ientRel easelsochPortProc calls each client of the channel to release its 
isochronous port. 

typedef OSStatus (FWClientReleaselsochPortProc) ( 

FWClientReleaselsochPortParamsPtr pFWClientReleaselsochPortParams, 
UInt32 *pCommandAcceptance); 


<--> pFWClientReleaselsochPortParams 

--> refCon 

--> portlsTalker 

<-- pCommandAcceptance 


Pointer to parameter block. 

Reference constant specific to 
this port. 

If false, port is for listening; 
otherwise, port is for 
talking. 

Value returned specifying 
acceptance of current and 
future commands. 
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DESCRIPTION 

When an isochronous channel is being released, each client of the channel is 
called through its FWClientReleaselsochPortProc interface procedure. The 
talking client is called first before each listening client has released the port. 

Each client should do whatever is necessary to release any resources allocated 
for its port. 

This procedure is called only at task level. 


2.4.8. FWClientStartlsochPortProc 

When the FireWire services library is asked to start running an isochronous 
channel, FWC1 i entStartlsochPortProc calls each client of the channel to start its 
isochronous port. 

typedef OSStatus (FWClientStartlsochPortProc) ( 

FWC1ientlsochPortActionParamsPtr pFWClientIsochPortAction Pa rams, 

UInt32 *pCommandAcceptance); 


<- - > pFWCli entlsochPortAction Pa rams 

--> refCon 

--> portlsTalker 

<-- pCommandAcceptance 


Pointer to parameter block. 

Reference constant specific to 
this port. 

If false, port is for listening; 
otherwise, port is for 
talking. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

When an isochronous channel is being started, each client of the channel is 
called through its FWCli entStartlsochPortProc interface procedure. The talking 
client is called last after each listening client has started listening to the channel. 

Each client should do whatever is necessary to start its port listening or talking. 

This procedure may be called in any environment except primary interrupt 
level. 
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2.4.9. FWClientStopIsochPortProc 

When the FireWire services library is asked to stop running an isochronous 
channel, FWClientStopIsochPortProc calls each client of the channel to stop its 
isochronous port. 

typedef OSStatus (FWClientStopIsochPortProc) ( 

FWClientlsochPortActionParamsPtr pFWClientlsochPortAction Pa rams, 

UInt32 *pCommandAcceptance); 


<--> pFWClientlsochPortActionParams 

--> refCon 

--> portlsTalker 

<-- pCommandAcceptance 


Pointer to parameter block. 

Reference constant specific to 
this port. 

If false, port is for listening; 
otherwise, port is for 
talking. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

When an isochronous channel is being stopped, each client of the channel is 
called through its FWC1 i entStopIsochPortProc interface procedure. The talking 
client is called first before each listening client has stopped listening to the 
channel. 

Each client should do whatever is necessary to stop its port listening or talking. 

This procedure may be called in any environment except primary interrupt 
level. 
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FireWire Device Driver 
Architecture 


This chapter describes the specific requirements for constructing FireWire 
device drivers for use with the Mac OS. The FireWire device driver architecture 
follows the native driver family guidelines documented in Designing PCI Cards 
and Drivers. Hence, all FireWire drivers must conform to the guidelines for 
writing native drivers specified there. All FireWire drivers must also conform 
to the additional guidelines for the FireWire driver family specified in this 
chapter. 


3.1 FireWire Driver Framework 


3.1.1 FireWire Driver Data Exports 

The FireWire driver family does not require any data exports other than those 
specified in Designing PCI Cards and Drivers. However, the FireWire driver 
family requires that the dri verName field in TheDri verDescri pti on must be 
fvxxxx,yyyy where xxxx is the device's Spec_Id and yyyy is the device's 
Sw_Versi on. Both these values must be hexadecimal numbers, without leading 
zeroes, that use lowercase for the letters a through/and are rendered as ASCII 
characters. 


3.1.2 FireWire Driver Code Exports 

The FireWire driver family architecture does not specify any code exports other 
than those specified by the driver family that the driver belongs to. For 
instance, a driver for a FireWire disk drive belongs to the generic driver family 
in Mac OS System 7.x or the block storage family in Mac OS System 8. For 
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System 7.x, this driver would contain a code export called DoDri verlO, just as 
any generic device driver would. 


3.2 Structures, Data Types, and Constants 


3.2.1 FireWire Driver Types 


typedef FWReferencelD FWDriverlD; 


3.3 Registering FireWire Drivers 


FireWire device drivers are implemented as FireWire clients, as described in 
Section 2. Thus, they may use the FireWire client services for registering client 
command and notification procedures. In addition, FireWire drivers may use 
the services described in this section. 


3.3.1 FWRegisterDriver 

FWRegi sterDri ver registers a given driver with the FireWire services and 
provides useful information for the driver. 


OSStatus FWRegisterDriver ( 

RegEntryIDPtr 
FWDriverlD 
CSRROMEntryID 
UIn 132 

--> pFWDriverRegEntry 

<-- pFWDriver ID 

<-- pCSRUnitlD 


--> fwDriverSpecificData 


pFWDriverRegEntry, 

*pFWDriverlD, 

*pCSRUnitlD, 

fwDriverSpecificData); 

Pointer to driver's Name 
Registry entry ID. 
Returned driver reference ID. 
Returned CSR configuration 
ROM entry ID for driver's 
CSR unit directory. 
Driver's private data records. 
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DESCRIPTION 

FWRegi sterDri ver registers with the FireWire services the driver associated with 
the device specified by pFWDri ver Reg Entry. It also provides information for use 
by the driver and the FireWire services. Upon initialization, a driver is typically 
called by its family expert loader and given its Name Registry entry ID. The 
driver uses this entry ID to identify itself to the FWRegi sterDri ver call. 

When a driver registers itself with the FireWire services, it is given a driver 
reference ID in pFWDri ver ID, which it can use to reference itself and the device it 
controls in various FireWire service calls. In addition, the driver is given in 
pCSRUnitID the CSR configuration ROM entry ID of the CSR unit directory it 
was loaded against. The driver can use this entry ID as a starting point to 
search the unit directory for information. 

The driver may specify a pointer to its private data records in 

fwDri verSpeci f i cData, which is passed to the driver when the FireWire services 

calls any of the driver's interface procedures. 

When FWRegi sterDri ver is called for a given name registry entry, it cannot be 
called again for the same name registry entry until FWUnregi sterDri ver is called. 


3.3.2 FWUnregisterDriver 

FWUnregi sterDri ver unregisters a given driver with the FireWire services. 

OSStatus FWUnregisterDriver ( 

FWDriverlD fwDriverlD); 

--> fwDriverlD Reference to driver to unregister. 


DESCRIPTION 

FWUnregi sterDri ver unregisters the given driver with the FireWire services. The 
driver may be subsequently reregistered with another call to FWRegi sterDri ver. 
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FireWire Protocol Driver 
Architecture 


The FireWire driver architecture defines a type of FireWire client called a 
protocol driver. Protocol drivers are typically used for peer-to-peer and 
networking communication over a FireWire bus. FireWire protocol drivers are 
implemented as standard Macintosh native drivers with some modifications to 
the loading mechanism. 

Standard FireWire drivers have a one-to-one correspondence to FireWire 
devices; FireWire protocol drivers have a one-to-one correspondence to 
FireWire busses. There is one instantiation of a FireWire protocol driver for 
each FireWire bus attached to the host. There may be more than one different 
FireWire protocol driver for each bus. 

Each FireWire protocol driver is added to the Name Registry once for each bus 
attached to the host. The protocol driver exports a data record that indicates the 
name of its entry in the Name Registry. Once the FireWire protocol driver's 
entry has been added to the Name Registry, it is loaded using the normal 
loading mechanisms for standard native drivers. 


4.1 FireWire Protocol Driver Framework 


4.1.1 FireWire Protocol Driver Data Exports 

The FireWire driver family requires that protocol drivers export 
TheDri verDescri pti on data record as all standard native drivers do. In addition, 
protocol drivers must export ThePDri verDescri pti on record, which specifies 
attributes of the protocol driver. This data record indicates the bus that the 
protocol driver runs on (FireWire) and the name to use in the Name Registry 
for the protocol driver. This name should be the same as the driver name 
specified in the protocol driver's TheDri verDescri pti on data record. 


4.1 FireWire Protocol Driver Framework 


57 



CHAPTER 4 


FireWire Protocol Driver Architecture 


4.1.2 FireWire Protocol Driver Code Exports 

The FireWire driver family architecture does not specify any code exports other 
than those specified by the family that the driver belongs to. For instance, a 
driver for a FireWire disk drive belongs to the generic driver family in Mac OS 
System 7.x or the block storage family in Mac OS System 8. For System 7.x, this 
driver would contain a code export called DoDri verlO, just as any generic 
device driver would. 

4.1.3 FireWire Protocol Driver File Type 

The FireWire driver family will automatically scan the extension folder for files 
of type ' fwpd ', the file type for FireWire protocol drivers. 


4.2 Structures, Data Types, and Constants 


4.2.1 FWPDriverDescription 


enum 


kTheFWPDriverDescriptionSi gnature = ’pdei', 

klnitialFWPDriverDescriptor = 0 

) ; 

kTheFWPDri verDescri pti onSi gnature Signature used to identify protocol 

driver description record. 

klni tial FWPDri verDescri ptor Initial protocol driver description 

record version number. 


typedef UInt32 FWPDriverDescVersion ; 

typedef OptionBits FWPDriverLoadingOptions ; 


FWPDriverDescVersion 
FWPDriverLoadingOptions 


Type used for version of protocol 
driver description record. 
Type used for protocol 

driver loading options. 
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struct FWPDriverTypeStruct 


OSType 
NumVersion 


fwPDriverServiceCategory; 
fwPDriverVersion; 


typedef struct FWPDriverTypeStruct 


FWPDriverType, 
*FWPDriverTypePtr; 


fwPDriverServiceCategoryy 
fwPDriverVersion 


Service category of bus that this 
protocol driver runs on. 
Protocol driver version number. 


struct FWPDriverLoadinglnfoStruct 
{ 

FWPDriverLoadingOptions fwPDriverLoadingOptions; 

Str31 fwPDriverName; 

}; 

typedef struct FWPDriverLoadinglnfoStru FWPDriverLoadinglnfo, 

*FWPDriverLoadinglnfoPtr; 


fwPDri verLoadi ngOpti ons Options for controlling loading 

of protocol driver. 

fwPDri verName Name to use for protocol driver's 

Name Registry entry. 


struct FWPDriverDescriptionStruct 


OSType 

fwPD 

FWPDriverDescVersion 

fwPD 

FWPDriverType 

fwPD 

FWPDriverLoadinglnfo 

fwPD 


verDescSignature; 
verDescVersion; 
verType; 
verLoadinglnfo; 


typedef struct FWPDriverDescriptionStruct FWPDriverDescription, 

*FWPDriverDescriptionPtr; 


fwPDr" 

i verDescSignature 

Signature field of this structure. 

fwPDr" 

i verDescVersion 

Version of this structure 

fwPDr" 

i verType 

Type of protocol driver. 

fwPDr" 

i verLoadinglnfo 

Loading information for 



protocol driver. 
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4.2.2 FWPDriverProtocol 


sped D; 
swVersion; 

Struct FWPDriverProtocol, 

*FWPDriverProtocolPtr; 

s p e c ID CSR configuration ROM s p e c ID 

of protocol. 

swVersion CSR configuration ROM 

swVersi on of protocol. 


struct FWPDriverProtocolStruct 
{ 

UInt32 

UInt32 

) ; 

typedef struct FWPDriverProtocol 


4.2.3 FireWire Protocol Driver Types 


typedef FWReferencelD FWPDriverlD; 

typedef FWReferencelD FWUnitID; 


typedef OSStatus (FWPDriverUnitAddedProc) ( 

FWPDriverlD fwPDriverlD, 

UInt32 fwPDriverSpecificData , 

FWUnitlD fwUnitlD) ; 


typedef FWPDriverUnitAddedProc *FWPDriverUnitAddedProcPtr; 


typedef OSStatus (FWPDriverUnitRemovedProc) ( 

FWPDriverlD fwPDriverlD, 

UInt32 fwPDriverSpecificData , 

FWUnitlD fwUnitlD) ; 


typedef FWPDriverUnitRemovedProc *FWPDriverUnitRemovedProcPtr; 


FWPDriverID 
FWPUnitID 

FWPDriverUnitAddedProc 
FWPDriverUnitRemovedProc 


FireWire reference to protocol driver. 

FireWire reference to a CSR 
configuration ROM unit. 

Proc to call when a new 

protocol unit has been added. 

Proc to call when a protocol 
unit has been removed. 
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4.3 Writing FireWire Protocol Drivers 


FireWire protocol drivers are implemented as FireWire clients as described in 
Section 2. Thus, they may use the FireWire client services for registering client 
command and notification procedures. In addition, FireWire drivers may use 
the following services. 


4.3.1 FWRegisterProtocolDriver 

FWRegi sterProtocol Dri ver registers a given protocol driver with the FireWire 
services and provides useful information for the protocol driver. 


OSStatus FWRegisterProtocolD 

RegEntryIDPtr 
FWPDriverlD 
UInt32 

--> pFWPDriverRegEntry 

<-- pFWPriverlD 

--> fwPDriverSpecificData 


river ( 

pFWPDri verRegEntry, 

*pFWPriverlD, 

fwPDriverSpecificData); 

Pointer to protocol driver's 
Name Registry entry ID. 

Returned protocol driver reference ID. 
Protocol driver's private data records. 


DESCRIPTION 

FWRegi sterProtocol Dri ver registers the protocol driver associated with the 
Name Registry entry specified by pFWDri verRegEntry with the FireWire services 
and provides information for use by the protocol driver and the FireWire 
services. Upon initialization, a protocol driver is typically called by its family 
expert loader and given its Name Registry entry ID. The protocol driver uses 
this entry ID to identify itself to the FWRegi sterProtocol Driver call. 

When a protocol driver registers itself with the FireWire services, it is given its 
protocol driver reference ID in pFWPDri ver ID, which it can use to reference itself 
in various FireWire service calls. 

The protocol driver may specify a pointer to its private data records in 
fwPDri verSpeci f i cData, which is passed to the protocol driver when the 
FireWire services calls any of the protocol driver's interface procedures. 


4.3 Writing FireWire Protocol Drivers 
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When FWRegi sterProtocol Dri ver is called for a given name registry entry it 
cannot be called again for the same name registry entry until 

FWUnregi sterProtocol Dri ver is called. 


4.3.2 FWUnregisterProtocolDriver 

FWUnregisterProtocolDriver unregisters a protocol driver with the FireWire 
services. 

OSStatus FWUnregisterProtocolDriver ( 

FWPDriverlD fwPDriverlD); 

--> fwPDri verlD Reference to protocol driver 

to unregister. 


DESCRIPTION 

FWUnregisterProtocolDriver unregisters the given protocol driver with the 
FireWire services. The protocol driver may be subsequently reregistered with 
another call to FWRegi sterProtocol Dri ver. 


4.3.3 FWSetPDriverProtocolTable 

FWSetPDriverProtocolTable specifies a table of protocols used by the protocol 
driver. 


OSStatus FWSetPDriverProtocolTable ( 


FWPDriverlD 

FWPDriverProtocolPtr 

UInt32 

--> fwPDriverlD 

--> fwPDriverProtocolTable 

--> tableSize 


fwPDriverlD, 

fwPDriverProtocolTable, 

tableSize); 

Reference to protocol driver 
to set protocol table for. 
Table of protocols used by 
protocol driver. 
Number of entries in table. 
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DESCRIPTION 

FWSetPDri verProtocolTable specifies a table of protocols used by the protocol 
driver. This table consists of entries of CSR configuration ROM spec ID and 
swVersi on numbers of protocols that the protocol driver may use. Whenever the 
FireWire services detect a device with a unit with these specID and swVersi on 
combinations, they send notification of the unit's addition or removal through 
the protocol driver's unit added and unit removed interfaces. This table will be 
copied by FWSetPDriverProtocolTable and hence may be deallocated after the 
call returns. 


4.3.4 FWGetPDriverProtocolTable 

FWGetPDri verProtocol Table returns the table of protocols used by the protocol 
driver. 


OSStatus FWGetPDriverProtocolTable ( 

FWPDriverlD fwPDriverlD, 

FWPDriverProtocolPtr fwPDriverProtocolTable, 

UIn t3 2 *pTableSize, 

UInt32 maxTableSize); 


> fwPDriverlD 

> fwPDriverProtocolTable 

> pTableSize 

> maxTableSize 


Reference to protocol driver. 

to get protocol table for. 
Table of protocols used by 
protocol driver. 
Returned number of entries 
in table. 

Maximum number of 
entries allocated in 

fwPDri verProtocol Table, 


DESCRIPTION 

FWGetPDri verProtocol Table returns the table of protocols used by the protocol 
driver. The actual table size will be returned in pTabl eSi ze. If the actual table 
size is larger than the maximum table size specified by maxTabl eSi ze, the table 
will be truncated to maxTabl eSi ze entries to fit in fwPDri verProtocol Tabl e. 
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4.3.5 FWScanUnitsForFWPDriver 

FWScanUnitsForFWPDriver scans the bus for device units that the protocol driver 
is intereseted in. 

OSStatus FWScanUnitsForFWPDriver ( 

FWPDriverlD fwPDriverlD); 

--> fwPDri verlD Reference to protocol driver 

to scan units for. 


DESCRIPTION 

FWScanUnitsForFWPDriver scans the bus for units with a CSR configuration 
ROM sped D and swVersi on combination that matches any entry in the protocol 
driver's protocol table. Notification of a match is sent to the protocol driver 
through the protocol driver's unit added proc. Protocol drivers will typically 
call FWScanUnitsForFWPDriver after registering with the FireWire services to get 
an initial set of units. Thereafter, the FireWire services will notify the protocol 
driver when any interesting units are added or removed. 


4.3.6 FWSetFWPDriverUnitAddedProc 

FWSetFWPDri verUni tAddedProc specifies the procedure to call when an 
interesting unit is added to the bus. 


OSStatus FWSetFWPDriverUnitAddedProc ( 

FWPDriverlD fwPDriverlD, 

FWPDriverUnitAddedProcPtr fwPDriverUnitAddedProc); 


> fwPDriverlD 

> fwPDriverUnitAddedProc 


Reference to protocol driver 

to set the unit added proc for. 

Procedure to be called when 
interesting units are added 
to the bus. 


DESCRIPTION 

FWSetFWPDri verUni tAddedProc specifies the procedure to call when an 
interesting unit is added to the bus. Interesting units are those units whose CSR 
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configuration ROM spec ID and swVersion numbers match some entry in the 
protocol driver's protocol table. The protocol driver's unit added procedure 
will also be called for each unit found by a call to FW S c a n U n i t s F o r FW P D r i v e r. 


4.3.7 FWGetFWPDriverUnitAddedProc 

FWGetFWPDri verUni tAddedProc returns the procedure to call when an interesting 
unit is added to the bus. 


OSStatus FWGetFWPDriverUnitAddedProc ( 

FWPDriverlD fwPDriverlD, 

FWPDriverUnitAddedProcPtr *pFWPDriverUnitAddedProc); 


> fwPDriverlD 

> pFWPDriverUnitAddedProc 


Reference to protocol driver 

to get the unit added proc for. 

Returned procedure to be 
called when interesting 
units are added to the bus. 


DESCRIPTION 

FWGetFWPDri verUni tAddedProc returns the unit added procedure set by the last 

call to FWSetFWPDri verUni tAddedProc. 


4.3.8 FWSetFWPDriverUnitRemovedProc 

FWSetFWPDri verUnitRemovedProc specifies the procedure to call when an 
interesting unit is removed from the bus. 


OSStatus WSetFWPDriverUnit 

FWPDriverlD 

FWPDriverUnitRemovedProcPtr 
--> fwPDriverlD 

--> fwPDriverUnitRemovedProc 


vedProc ( 

fwPDri verlD, 

fwPDriverUnitRemovedProc); 

Reference to protocol driver to set 
the unit removed proc for. 

Procedure to be called when 
interesting units are 
removed from the bus. 


Remo 
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DESCRIPTION 

FWSetFWPDri verUni tRemovedProc specifies the procedure to call when an 
interesting unit is removed the bus. Interesting units are those units whose CSR 
configuration ROM spec ID and swVersi on numbers match some entry in the 
protocol driver's protocol table. 


4.3.9 FWGetFWPDriverUnitRemovedProc 

FWGetFWPDri verUni tRemovedProc returns the procedure to call when an 
interesting unit is removed from the bus. 


OSStatus FWGetFWPDriverUni 

FWPDriverl D 

FWPDriverUnitRemovedProcPtr 
--> fwPDriverlD 
--> pFWPDriverUnitRemovedProc 


edProc ( 

fwPDriverlD, 

*pFWPDriverUnitRemovedProc); 

Reference to protocol driver to get 
the unit removed proc for. 

Returned procedure to be called 
when interesting units are 
removed from the bus. 


tRemov 


DESCRIPTION 

FWGetFWPDri verUni tRemovedProc returns the unit removed procedure set by the 
last call to FWSetFWPDri verUni tRemovedProc. 


4.3.10 FWAddUnitConnection 

FWAddUni tConnecti on adds a connection to the given unit. 


OSStatus FWAddUnitConnection 

FWUnitID 
FWReferencelD 

--> fwUnitID 

--> fwReferencelD 


( 

fwUnitlD, 
fwReferencelD); 

Unit to add connection to. 
Reference to client to add unit 
connection for. 
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DESCRIPTION 

FWAddUni tConnecti on adds a connection to the given unit. This connection 
indicates that the client specified by fwReferencel D has a dependency on the 
unit. While there are open connections to a unit, the FireWire services will not 
release the unit reference even if the unit is removed from the bus. 

FWAddUni tConnecti on may be called more than once for the same unit. FireWire 
protocol drivers will typically add a connection to new units when their unit 
added procs are called. 


4.3.11 FWRemoveUmtConnection 

FWRemoveUni tConnecti on removes a connection from the given unit. 


OSStatus FWRemoveUnitConne 

FWUnitID 
FWReferencelD 

--> fwUnitID 

--> fwReferencelD 


ction ( 

fwUnitID, 
fwReferencelD); 

Unit to remove connection from. 
Reference to client to remove 
unit connection for. 


DESCRIPTION 

FWRemoveUni tConnecti on removes a connection from the given unit. This 
connection indicates that the client specified by fwReferencel D no longer has a 
dependency on the unit. Only when a unit is disconnected from the bus and all 
connections to the unit have been removed will the FireWire services release 
the unit reference. FireWire protocol drivers will typically remove a connection 
to a unit after their unit removed proc is called. Flowever, they may often wait 
until higher level dependencies on the unit are removed before calling 
FWRemoveUnitConnection. 
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4.4 FireWire Protocol Driver Interface Procedures 


4.4.1 FWPDriverUnitAddedProc 

FWPDri verUni tAddedProc is called when an interesting unit is added to the bus. 


typedef OSStatus 
FWPDriverID 
UInt32 
FWUnitID 


(FWPDriverUnitAddedProc) ( 
fwPDriverlD, 
fwPDriverSpecif i cData , 
fwUnitlD) ; 


--> fwPDri verlD Reference to protocol driver 

being called. 

- -> fwPDri verSpeci f i cData Protocol driver's private data records. 

--> fwUni tID Reference to added unit. 


DESCRIPTION 

When a new unit is detected on the bus that a protocol driver is interested in, 
the protocol driver is notified through its unit added proc. A reference to the 
unit is passed in with fwUni 11D. This reference may be used in the various 
FireWire service routines to target the device that the unit resides in. 

The protocol driver's unit added proc will also be called for each interesting 
unit when the protocol driver calls FWScanUnitsForFWPDriver. 

The protocol driver's unit added proc will always be called from task level. 


4.4.2 FWPDriverUnitRemovedProc 

FWPDri verUni tRemovedProc is called when an interesting unit is removed from 
the bus. 


typedef OSStatus 
FWPDriverlD 
UInt32 
FWUnitID 


(FWPDriverUnitRemovedProc) ( 
fwPDriverlD, 
fwPDriverSpecif i cData , 
fwUnitlD) ; 
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--> fwPDriverlD 

--> fwPDriverSpecificData 

--> fwUnitID 


Reference to protocol driver 
being called. 

Protocol driver's private data records 
Reference to removed unit. 


DESCRIPTION 

When a unit is removed from the bus that a protocol driver is interested in, the 
protocol driver is notified through its unit removed proc. A reference to the 
unit is passed in with fwUni tl D. 

The protocol driver's unit removed proc will always be called from task level. 


4.4 FireWire Protocol Driver Interface Procedures 
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A FireWire Interface Module (FWIM) is a piece of driver software that the 
FireWire driver family services use to access a FireWire bus. The FWIM 
architecture abstracts the hardware specifics of a FireWire card into a set of 
standard interfaces. This allows the FireWire driver family architecture to 
support multiple cards from multiple vendors in a single system. 

The FWIM architecture follows the native driver family guidelines documented 
in Designing PCI Cards and Drivers. Hence, all FWIMs must conform to the 
guidelines for writing native drivers specified there. All FWIMs must also 
conform to the additional guidelines specified for the FireWire driver family in 
this document. 


5.1 FireWire Interface Module Framework 


5.1.1 FWIM Data Exports 

The FireWire driver family requires one data exports in addition to those 
specified in Designing PCI Cards and Drivers. With regards to the standard 
driver data exports, the FireWire driver family requires that the exported data 
structure TheDri verDescri pti on contain a Dri verServi celnfo entry with the 
servi ceCategory equal to kServi ceCategoryFWIM ('fwim'). 

In addition, the FireWire driver family requires the FWIM to export a data 
structure called ThePl ugi nDi spatchTabl e that contains procedure pointers to all 
of the entry points into the FWIM. The format of this table is described below. 


5.1 FireWire Interface Module Framework 
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5.1.2 FWIM Code Exports 

The FireWire driver family architecture does not specify any code exports for a 
FWIM. 


5.2 Structures, Data Types, and Constants 


5.2.1 FWIMPIuginDispatchTable 


struct FWIMPluginDispatchTableStruct 

{ 

UInt32 

FWIMInitializeProcPtr 

FWIMFinalizeProcPtr 

FWIMPollInterruptsProcPtr 

FWIMSendPhyPacketProcPtr 

FWIMSendPhyPacketProcPtr 

FWIMAsynchT ransactionProcPtr 

FWIMSendAsynchResponsePacketProcPtr 

FWIMAsynchT ransactionProcPtr 

FWIMSendAsynchResponsePacketProcPtr 

FWIMAsynchT ransactionProcPtr 

FWIMSendAsynchResponsePacketProcPtr 

FWIMAllocatelsochPortProcPtr 

FWIMReleaselsochPortProcPtr 

FWIMControlIsochPortProcPtr 

FWIMControlIsochPortProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMCommandProcPtr 

FWIMGetUniquelDProcPtr 

) ; 


piuginVersion ; 

fwiminitializeProc; 

fwimFinalizeProc; 

fwimPollInterruptsProc; 

fwimSendLinkOnPacketProc; 

fwimSendPhyConfigurationPacketProc; 

fwimReadProc; 

fwimReadResponseProc; 

fwimWriteProc; 

fwimWriteResponseProc; 

fwimLockProc; 

fwimLockResponseProc; 

fwimAllocatelsochPortProc; 

fwimReleaselsochPortProc; 

fwimStartlsochPortProc; 

fwimStopIsochPortProc; 

fwimResetBusProc; 

fwimSetContenderBitProc; 

fwimClearContenderBitProc; 

fwimEnableCycleMasterProc; 

fwimDisableCycleMasterProc; 

fwimSetRootHoldoffBitProc; 

fwimClea rRootHoldoffBitProc; 

fwimGetUniquel DP roc; 
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typedef struct FWIMP1uginDispatchTableStruct 

FWIMPluginDispatchTable, 

*FWIMPluginDispatehTablePtr; 


piuginVersion 

fwimlnitia1izeProc 

fwimSendLinkOnPacketProc 

fwimSendPhyContigurationPacketProc 

fwirriReadProc 

fwimReadResponseProc 

fwimWriteProc 

fwimWriteResponseProc 

fwirriLockProc 

fwimLockResponseProc 

fwimAllocate IsochPortProc 

fwirriReleaselsochPortProc 

fwimStartlsochPortProc 

fwimStopIsochPortProc 

fwimResetBusProc 

fwimSetContenderBitProc 

fwimClearContenderBitProc 

fwiniEnableCycleMasterProc 

fwimDisableCycleMasterProc 

fwimSetRootHoldoffBitProc 

fwimClear RootHoidoffBitProc 

fwimGetUniquelDProc 


Specifies version of the dispatch table. 
Proc to initialize the FWIM. 

Proc to send a link on packet. 

Proc to send a phy configuration packet. 
Proc to perform a read transaction. 

Proc to send a read response packet. 
Proc to perform a write transaction. 

Proc to send a write response packet. 
Proc to perform a lock transaction. 

Proc to send a lock response packet. 

Proc to allocate an isochronous port. 
Proc to release an isochronous port. 

Proc to start an isochronous port. 

Proc to stop an isochronous port. 

Proc to initiate a bus reset. 

Proc to set the contender bit. 

Proc to clear the contender bit. 

Proc to enable cycle mastering. 

Proc to disable cycle mastering. 

Proc to set the root holdoff bit. 

Proc to clear the root holdoff bit. 

Proc to get the unique ID. 


5.2.2 FWIMInitializeParams 


struct FWIMInitializeParamsStruct 
f 

UInt32 fwimSpecificData ; 

FWIMID fwimlD; 

RegEntrylD fwimRegEntrylD; 

); 

typedef struct FWIMInitializeParamsStruct 

FWIMInitializeParams, 

* FWIMIn itializeParamsPtr; 


5.2 Structures, Data Types, and Constants 
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fwimSpecificData 
fwiml D 

fwi mRegEntryID 


FWIM's private data; passed to FWIM on 
subsequent calls. 

Reference to the FWIM; used in subsequent 
calls to the FireWire services. 

Reference to Name Registry entry for FWIM. 


5.2.3 FWIMFinalizeParams 


struct FWIMFinalizeParamsStruct 
{ 

UInt32 
FWIMID 
RegEntryID 

} 

typedef struct FWIMFinalizeParamsSt 


fwimSpecificData 

fwimlD 

fwimRegEntryID 


fwi mSpeci f icData ; 
f w i m ID ; 

fwi mRegEntryID; 

■uct 

FWIMFi nal i zeParams , 

* FW IM Final i zeParamsPtr; 

Data for use by FWIM. This is the same 
data returned by the FWIM in calls 
to the FWIM's Initialize proc. 
Reference to FWIM target of command. 
Reference to Name Registry entry 
for FWIM. 


5.2.4 FWIMPollInterruptsParams 


struct FWIMPollInterruptsParamsStruct 
f 

UInt32 fwimSpecificData ; 

FWIMID fwimlD; 

RegEntrylD fwimRegEntryID; 

) 

typedef struct FWIMPol1InterruptsParamsStruct 

FWIMPollInterruptsParams, 

*FWIMPollInterruptsParamsPtr; 


74 


5.2 Structures, Data Types, and Constants 



CHAPTER 5 


FireWire Interface Module Architecture 


fwimSpecificData 


fwimID 

fwimRegEntrylD 


Data for use by FWIM. This is the same 
data returned by the FWIM in calls 
to the FWIM's Initial ize proc. 

Reference to FWIM target of command. 

Reference to Name Registry entry 
for FWIM. 


5.2.5 FWlMCommandParams 


struct FWIMCommandParamsStruct 
f 

UInt32 

FWIMID 

Ptr 

FWIMCommandlD 

) 

typedef struct FWIMCommandParamsStru 


commandType 

fwimID 

fwi mSpecificData 

fwimCommandID 


commandType; 
fwimID; 

fwimSpecificData ; 
fwimCommandID; 

ct 

FWlMCommandParams, 
*FWIMCommandParamsPtr; 

Type of command being made to FWIM. 
Reference to FWIM target of command. 
Data for use by FWIM. This is the same 
data returned by the FWIM in calls 
to the FWIM's Ini ti al i ze proc. 
Reference to this command; used 
in call to FWIMCommandlsCompl ete. 


5.2.6 FWlMGetUniquelDParams 


struct FWIMGetUniquelDParamsStruct 


{ 

FWlMCommandParams 
CSRNodeUniquelD 

); 


fwimCommandParams; 
uniquelD; 
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typedef struct FWIMGetUniquelDParamsStruct 

FWIMGetUniquelDPa rams, 

*FWIMGetUniquelDParamsPtr; 

fwi mCommandPa rams Parameters common to all FWIM 

commands. 

uni quel D Unique ID of local node. 


5.2.7 FWIMSendPhyPacketParams 


struct FWIMSendPhyPacketParamsStruct 


{ 

FWIMCommandParams 

UInt32 

Ptr 

UInt32 

UInt32 

) 

typedef struct FWIMSendPhyPacketPara 


fwimCommandPa rams 
generation 

buffer 
1ength 

commandStorage 


fwimCommandPa rams; 
generation; 
buffer; 

1ength ; 

commandStorage 

msStruct 

FWIMSendPhyPacketParams, 

*FWIMSendPhyPacketParamsPtr 

Parameters common to all FWIM 
commands. 

Generation value of the topology 
map that the physical layer 
packet was constructed with. 
Buffer with phy packet data. 

Length of phy packet data. 

32-bit storage for common phy packets. 


5.2.8 FWIMAsynchCommandParams 


struct FWIMAsynchCommandParamsStruct 
f 

FWIMCommandParams fwimCommandParams; 

Duration timeout; 

UInt32 generation; 
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Ptr 

buffer; 

UI n 18 

numRetries; 

UI n 18 

speed; 

UI n 116 

reserved 

UI n 13 2 

addressFli , 


address Lo; 

UI n 116 

1ength; 

UI n 116 

extendedTCode 


); 

typedef struct FWIMAsynchCommandParamsStruct 

FWIMAsynchCommandParams, 
*FWIMAsynchCommandParamsPtr; 


fwimCommandParams 

Parameters common to all FWIM 
commands. 

timeout 

Split transaction timeout period. 

generation 

Generation value of topology map 
that the target address was 
generated from. 

buffer 

Buffer to transfer data into or out of. 

numRetri es 

Number of times to retry command 

speed 

Speed at which to transmit packets. 

addressHi, address Lo 

64-bit target address. 

1ength 

Length of data in buffer. 

extendedTCode 

Extended transaction code for 
lock commands. 


5.2.9 FWIMAsynchResponseCommandParams 

struct FWIMAsynchResponseCommand Pa rams Struct 

1 

i 

FWIMCommandParams 

fwimCommandParams; 

AbsoluteTime 

timeout; 

UInt32 

generation; 

Ptr 

buffer; 

UInt8 

numRetries 

UInt8 

speed; 

UI n 116 

transaction Descriptor; 

UI n 116 

destination ID; 

UI n 116 

responseDataHi; 
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UInt32 responseDataLo; 

UIn 116 length; 

UIn 116 extendedTCode; 


typedef struct FWIMAsynchResponseCommandParamsStruct 

FWIMAsynchResponseCommandPa rams, 

*FWIMAsynchResponseCommandPa ramsPtr; 


fwimCommandPa rams 

timeout 
generation 

buffer 
numRetries 
speed 

transactionDescriptor 

destinationID 
responseDataHi, 
responseData Lo 
1ength 

extendedTCode 


Parameters common to all FWIM 
commands. 

Time the response must be sent before. 
Bus generation value for which 
response is valid. 

Buffer with response data. 

Number of times to retry command. 
Speed to transmit response. 

Transaction descriptor for response. 

Includes transaction label. 

Node ID of the target of the response. 
Response header data. 

Amount of response data. 

Extended transaction code for response. 


5.2.10 FWIMIsochPortCommandParams 


struct FWIMIsochPortCommandParamsStruct 
{ 

IsochPortID isochPortID; 

UInt32 fwimlsochPortData; 

) ; 

typedef struct FWIMIsochPortCommandParamsStruct 

FWIMIsochPortCommandParams, 
*FWIMIsochPortCommandPa ramsPtr; 

Reference to isochronous port target 
of command. 

Data for FWIM to use as it needs. 


isochPortlD 
fwimlsochPortData 
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5.2.11 FWIMAIIocatelsochPortParams 


struct FWIMA11 ocatellochPortPa ramsStruct 


FWIMCommandParams 
FWIMIsochPortCommandParams 
DCLProgramID 
UI n 1 3 2 
UI n 1 3 2 


Boolean 


fwimCommandParams; 

fwimlsochPortCommandParams; 

delProgramID; 

channelNum; 

speed; 

talking; 


typedef struct 


FWIMAllocatelsochPortParamsStruct 

FWIMAIIocatelsochPortParams, 

*FWIMAllocateIsochPortParamsPtr; 


fwimCommandParams 

fwimlsochPortCommandParams 

delProgramID 
channelNum 
speed 
talking 


Parameters common to all FWIM 
commands. 

Parameters common to all FWIM 
isochronous port commands. 

ID of DCL program to use with this port. 

Desired channel number of allocated port. 

Desired speed of allocated port. 

If true, allocated port is used for talking; 
otherwise, allocated port is 
used for listening. 


5.2.12 FWIMReleaselsochPortParams 


struct FWIMReleaselsochPortParamsStruct 
{ 

FWIMCommandParams fwimCommandParams; 

FWIMIsochPortCommandParams fwimlsochPortCommandParams; 

); 

typedef struct FWIMReleaselsochPortParamsStruct 

FWIMReleaselsochPortParams, 

*FWIMReleaseIsochPortParamsPtr; 
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fwimCommandPa rams Parameters common to all FWIM 

commands. 

fwi mlsochPortCommandPa rams Parameters common to all FWIM 

isochronous port commands. 


5.2.13 FWIMIsochPortControlParams 


struct FWIMIsochPortControlParamsStruct 

{ 

FWIMCommandPa rams fwimCommandPa rams 

FWIMIsochPortCommandPa rams fwimlsochPortCommandParams; 

) ; 

typedef struct FWIMIsochPortControlParamsStruct 

FWIMIsochPortControlParams, 

*FWIMIsochPortControlParamsPtr; 

fwi mCommandPa rams Parameters common to all FWIM 

commands. 

fwi mlsochPortCommandPa rams Parameters common to all FWIM 

isochronous port commands. 


5.2.14 FWIMProcessParams 


struct FWIMProcessParamsStruct 
f 


FWIMProcessParamsPtr 

pNextFWIMProcessPara 

UInt32 

processType; 

FWIM ID 

fwimlD; 

UInt32 

processFlags; 

UInt32 

processState; 

UInt32 

processStatus; 

FWIMProcessID 

fwimProcessID; 

FWIMProcessCompletionProcPtr 

completionProc; 

UInt32 

completionProcData; 

def struct FWIMProcessParamsStruct 


FWIMProcessPa rams, 

*FWIMProcessParamsPtr; 
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pNextFWIMCommandParams 

processType 

fwimID 

processFlags 
processState 
processStatus 
fwimProcessID 
completionProc 

completionProcData 


Link to next process parameter record 
in process command queue. 

Type of processing requested by FWIM. 
ID of FWIM making process request. 
Flags controlling processing. 

Current state bits of processing. 

Final status of processing 
Reference to this processing request. 
Procedure to call upon processing 
completion. 

Data for use by completion procedure. 


5.2.15 FWIMProcessSelfIDsParams 


struct FWIMProcessSelfIDsParamsStruct 


FWIMProcessParams 

UI n 13 2 

Ptr 

UI n 13 2 
Ptr 

UI n 13 2 
UI n 13 2 


fwimProcessParams; 
generation; 
pSelfIDList; 
selfIDListSize; 
pLocalSelfID; 

1ocalSelfIDSize; 
processSelfIDsFlags; 


typedef struct FWIMProcessSelfIDsParamsStruct 

FWIMProcessSelfIDsParams, 

*FWIMProcessSelfIDsParamsPtr; 


fwimProcessParams 

generation 
pSelfIDList 
sel f I DLi stSi ze 
pLocalSelf ID 
1ocalSelfIDSize 
processSelfIDsFlags 


Parameters common to all FWIM processing 
requests. 

Returned topology generation value. 

Pointer to list of received self IDs. 

Size of self ID list. 

Pointer to list of local self ID. 

Size of local self ID 

Flags controlling processing of self IDs. 
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5.2.16 FWIMProcessAsynchParams 


FWIMProcessAsynchPa ramsStruct 


struct 
{ 

FWIMProcessParams 
AbsoluteTime 
UInt32 
Ptr 

UI n 116 
UI n 116 
UI n 116 
UI n 116 
UInt32 
UInt16 
UI n 116 
UInt32 


fwimProcessParams ; 
timeStamp; 
generation; 
receiveBuffer; 
destination ID; 
transactionDescriptor; 
sourcelD; 
addresshli ; 
addressLo; 

1ength ; 

extendedTCode; 
transactionStatus; 


typedef struct FWIMProcessAsynchParamsStruct 

FWIMProcessAsynchPa rams, 

*FWIMProcessAsynchPa ramsPtr; 


fwimProcessPa rams 

timeStamp 
generation 

receiveBuffer 
destinationID 

transactionDescriptor 

sourcelD 

addressHi, addressLo 
1ength 

extendedTCode 
transactionStatus 


Parameters common to all FWIM processing 
requests. 

Time that request packet was received. 

Topology generation for which packet was 
received. 

Buffer with received asynchronous packet data. 

Node ID of destination of received 

asynchronous packet (may be ignored). 

Transaction descriptor for response. 

Includes transaction label. 

Node ID of source of received asynchronous 
packet. 

48-bit target address offset of received 
asynchronous packet. 

Length of payload of received packet. 

Extended transaction code of received packet. 

Transaction status for request packet. 

Includes ackCode and speed. 
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5.2.17 FWIM Types 


typedef Kernel ID 
typedef Kernel ID 
typedef Kernel ID 
typedef Kernel ID 


FWIMID; 

IsochPortID; 

FWIMCommandlD; 

FWDeferredTaskID; 


typedef OSStatus (FWIMInitializeProc) ( 

FWIMInitializeParamsPtr pFWIMInitializeParams); 

typedef FWIMInitializeProc FWIMInitializeProcPtr; 


typedef OSStatus (FWIMFinalizeProc) ( 

FWIMFinalizeParamsPtr pFWIMFinalizeParams); 

typedef FWIMFinalizeProc FWIMFinalizeProcPtr; 


typedef OSStatus (FWIMPol1InterruptsProc) ( 

FWIMPollInterruptsParamsPtr pFWIMPollInterruptsParams); 

typedef FWIMPol1InterruptsProc FWIMPol1InterruptsProcPtr; 


typedef OSStatus! FWIMCommandProc) 
FWIMCommandParamsPtr 
UInt32 

typedef FWIMCommandProc* 


pFWIMCommandParams, 
*pCommandAcceptance); 
FWIMCommandProcPtr; 


typedef OSStatus! FWIMSendPhyPacketProc) ( 

FWIMSendPhyPacketParamsPtr pFWIMSendPhyPacket Pa rams, 

UInt32 *pCommandAcceptance); 

typedef FWIMSendPhyPacketProc *FWIMSendPhyPacketProctr; 


typedef OSStatus! FWIMAsynchTransactionProc) ( 

FWIMAsynchCommandParamsPtr pFWIMAsynchCommandParams, 

UInt32 *pCommandAcceptance); 

typedef FWIMAsynchCommandProc *FWIMAsynchCommandProctr; 


typedef OSStatus! FWIMSendAsynchResponsePacketProc) ( 

FWIMAsynchResponseCommandParamsPtr pFWIMAsynchResponseCommandParams, 
UInt32 *pCommandAcceptance); 

typedef FWIMSendAsynchResponsePacketProc 

*FWIMSendAsynchResponse PacketProcPtr; 


5.2 Structures, Data Types, and Constants 


83 



CHAPTER 5 


FireWire Interface Module Architecture 


typedef OSStatus (FWIMA11ocatelsochPortProc) ( 

FWIMAllocatelsochPortParamsPtr pFWIMAllocatelsochPortParams, 

UInt32 *pCommandAcceptance); 

typedef FWIMA11ocatelsochPortProc *FWIMAllocateIsochPortProcPtr; 

typedef OSStatus (FWIMReleaselsochPortProc) ( 

FWIMReleaselsochPortParamsPtr pFWIMReleaselsochPortParams, 

UInt32 *pCommandAcceptance); 

typedef FWIMReleaselsochPortProc *FWIMReleaselsochPortProcPtr; 

typedef OSStatus (FWIMControl1IsochPortProc) ( 

FWIMIsochPortControlParamsPtr pFWIMIsochPortControlParams, 

UInt32 *pCommandAcceptance); 

typedef FWIMControl1IsochPortProc *FWIMControl1IsochPortProcPtr; 

typedef OSStatus (FWIMGetUniquelDProc) ( 

FWIMGetUniquelDParamsPtr pFWIMGetUniquelDPa rams, 

UInt32 *pCommandAcceptance); 

typedef FWIMGetUniquelDProc *FWIMGetUniquelDProcPtr; 

typedef void (FWIMCommandCompletionProc) ( 

FWIMCommandParamsPtr pFWIMCommandParams); 

typedef FWIMCommandCompletionProc *FWIMCommandCompletionProcPtr; 

typedef void (FWIMProcessCompletionProc) ( 

FWIMProcessParamsPtr pFWIMProcessParams); 

typedef FWIMProcessCompletionProc *FWIMProcessCompletionProcPtr; 


typedef void 
void 
void 

typedef FWDeferredTaskProc 


(FWDeferredTaskProc) ( 

*pa rami, 


*pa ram2); 

*FWDeferredTaskProcPtr; 


FWIMID 

IsochPortID 

FWIMCommandlD 

FWIMDeferredTasklD 

FWIMInitializeProc 

FWIMFinalizeProc 

FWIMPollInterruptsProc 


Reference to a FWIM. 

Reference to an isochronous port. 
Reference to a FWIM command. 
Reference to a FireWire deferred task. 
FWIM's intialization procedure. 
FWIM's finalization procedure. 
FWIM's interrupt polling procedure. 
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FWIMCommandProc FWIM's generic command handling 

procedure. 

FWIMSendPhyPacketProc FWIM's procedure for sending phy 

packets. 

FWIMAsynchTransacti onProc FWIM's procedure for performing 

asynchronous transactions. 

FWIMSendAsynchResponsePacketProc FWIM's procedure for sending 

asynchronous response packets. 

FWI MAI 1 ocatelsochPortProc FWIM's procedure for allocating 

isochronous ports. 

FWIMRel easelsochPortProc FWIM's procedure for releasing 

isochronous ports. 

FWIMControl 1 IsochPortProc FWIM's procedure for controlling 

isochronous ports. 

FWIMGetUni quelDProc FWIM's procedure for acquiring the 

local unique ID. 

FWIMCommandCompl eti onProc Routine that handles the completion of a 

FWIM command. 

FWIMProcessCompl eti onProc Routine that handles the completion of a 

FWIM processing request. 

5.2.18 FWIM Constants 

enum 

f 

klnvalidFWIMID = 0 

); 

klnval idFWIMID If a FWIM ID is equal to klnval id FW IMID, 

it is invalid. 

enum 

f 

klnvalidlsochPortID = 0 

); 

klnvalidlsochPortlD If an isochronous port ID is equal to 

kInvalidIsochPortID,itis invalid. 
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enum 

f 

klnvalidFWIMCommandID = 0 

} ; 

klnval i dFWIMCommandID If a command ID is equal to 

klnval idFWIMCommandID, it is invalid. 

enum 

{ 

klnvalidFWDeferredTaskID = 0 

); 

klnval idFWDeferredTaskID If a deferred task ID is equal to 

klnval i dFWIMCommandID, it is invalid. 

enum 

f 

kFWIMPluginVersion = version of plug-in dispatch table. 

); 

kFWIMPlug inversion This constant is used to specify the 

version of the FWIM plug-in dispatch 
table used. 

enum 

f 

kFWIMCommandAcceptNoMore = 0 

kFWIMCommandAcceptMore = 1, 

kFWIMCommandRejected = 2 

}; 

kFWIMCommandAcceptNoMore This constant specifies that the given 

command has been accepted but that no 
more can be accepted. 

kFWIMCommandAcceptMore This constant specifies that the given 

command has been accepted and more 
commands can be accepted. 

kFWIMCommandRejected This constant specifies that the given 

command has been rejected but the 
command may later be retried. 
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The following constants specify the types of commands that may be sent to a 
FWIM: 

enum 


kFWIMSendLinkOnPacket = 1, 

kFWIMSendPhyConfigurationPacket = 2, 

kFWIMRead = 3, 

kFWIMReadResponse = 4, 

kFWIMWrite = 5, 

kFWIMWriteResponse = 6, 

kFWIMLock = 7, 

kFWIMLockResponse = 8, 

kFWIMAl1ocatelsochPort = 9, 

kFWIMReleaselsochPort = 10, 

kFWIMStartlsochPort = 11, 

kFWIMStopIsochPort = 12, 

kFWIMResetBus = 13, 

kFWIMSetContenderBit = 14, 

kFWIMClearContenderBit = 15, 

kFWIMEnableCycleMaster = 16, 

kFWIMDisableCycleMaster = 17, 

kFWIMSetRootPlol doffBi t = 18, 

kFWIMCl earRootPlol doffBi t = 19, 

kFWIMGetUniquelD = 20 


kFWIMSendLinkOnPacket 

kFWIMSendPhyConfigurationPacket 

kFWIMRead 

kFWIMReadResponse 

kFWIMWrite 

kFWIMWriteResponse 

kFWIMLock 

kFWIMLockResponse 

kFWIMAl1ocatelsochPort 

kFWIMReleaselsochPort 

kFWIMStartlsochPort 

kFWIMStopIsochPort 


Send a link-on phy packet. 

Send a phy configuration phy packet. 

Perform a read transaction. 

Send a read response packet. 

Perform a write transaction. 

Send a write response packet. 

Perform a lock transaction. 

Send a lock response packet. 

Allocate an isochronous port. 

Release resources allocated for an 
isochronous port. 

Start an isochronous port talking/ 
listening. 

Stop an isochronous port talking/ 
listening. 
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kFWIMResetBus 

kFWIMSetContenderBit 

kFWIMClearContenderBit 

kFWIMEnableCycleMaster 
kFWIMDisableCycleMaster 
kFWIMSetRoottlol doffBi t 
kFWIMClearRoottlol doffBi t 
kFWIMGetUniquelD 

enum 


Initiate a reset. 

Set the contender bit in the s e 1 f ID 
packet on subsequent bus resets. 
Clear the contender bit in the s e 1 f ID 
packet on subsequent bus resets. 
Enable sending cycle-start packets. 
Disable sending cycle-start packets. 
Set phy's root holdoff bit. 

Clear phy's root holdoff bit. 

Return the local unique ID. 


kFWTransactionDescriptorTLabel = FWBitRange (16, 21), 

kFWTransactionDescriptorTLabel Phase = FWBi tRangePhase (16, 21) 


kFWT ransactionDescriptorTLabel 


enum 

f 

kFWResponseDataRCode 

kFWResponseDataRCodePhase 

); 

kFWResponseDataRCode 


enum 
{ 

kFWT ransactionStatusAckCode 
kFWT ransactionStatusAckCodePhase 
kFWT ransactionStatusSpeed 
kFWT ransactionStatusSpeedPhase 

); 


Location of transaction label 

within transacti onDescri ptor. 


= FWBitRange (16, 19), 

= FWBitRangePhase (16, 19) 

Location of response code within 

responseDataHi. 


= FWBitRange (28, 31), 

= FWBitRangePhase (28, 31) 
= FWBitRange (26, 27), 

= FWBitRangePhase (26, 27) 


kFWT ransactionStatusAckCode 
kFWT ransactionStatusSpeed 


Location of ack code within 

transactionStatus. 

Location of speed code within 

transactionStatus. 
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5.3 Writing FireWire Interface Modules 


5.3.1 FWIMPIuginDispatchTable 

Each FWIM must export a data record named ThePluglnDispatchTable that is 
used by the FireWire services to interface with the FWIM. This table contains 
all the entry points into the FWIM. In addition, it contains version information 
that must be set to kFWIMPlug inversion. The entry points specified in the table 
are described below. 


5.3.2 FWIMImtializeProc 

FWIMI n i t i a 1 i zeProc is called by the FireWire services to initialize the FWIM. 


typedef OSStatus (FWIMInitia 

FWIMInitializeParamsPtr 

<--> pFWIMInitializeParams 
<-- fwimSpecificData 


--> fwimlD 


--> fwimRegEntrylD 


izeProc) ( 

pFWIMInitializeParams); 

Pointer to parameter block. 

Private data used by FWIM. This 
data is passed in on subsequent 
calls to the FWIM. 

Reference to this FWIM. The FWIM 
passes fwimlD to many FireWire 
services calls to identify itself. 
Reference to FWIM's entry in the 
Name Registry. 


DESCRIPTION 

FWIMIni ti al izeProc is called by the FireWire driver family expert loader to 
initialize the FWIM. This call is made at task level, so the FWIM can do just 
about any initialization it requires. The FWIM can allocate memory and use all 
of the FireWire service calls. 

Typically, a FWIM allocates a private data structure to save the fwimlD among 
other values. It may return a pointer to this data structure in fwimSpeci f i cData. 
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On subsequent calls to the FWIM, the FWIM will be given this pointer so that it 
has access to its private data structure. 

FWIM Ini ti al i zeProc will be called only at task level. 


5.3.3 FWIMFinalizeProc 

FWIMFi nal i zeProc is called by the FireWire services to undo the initialization 
performed by the FWIM's Initialization proc. 


typedef OSStatus (FWIMFinalizeProc) ( 

FWIMFinalizeParamsPtr pFWIMFinalizeParams); 


<--> pFWIMFinalizeParams 
--> fwimSpecificData 

--> fwimlD 

--> fwimRegEntryID 


Pointer to parameter block. 
Private data used by FWIM. 

This is the value returned by 
FWIMIni ti al i zeProc. 
Reference to target FWIM. 
Reference to FWIM's entry in the 
Name Registry. 


DESCRIPTION 

FWIMFi nal i zeProc is called by the FireWire driver family expert loader to undo 
the initialization performed by FWIMIni ti al i zeProc. This call is made at task 
level, so the FWIM can do the deallocations it requires. The FWIM can 
deallocate memory and use any of the FireWire service calls. The parameter 
fwi mSpeci f i cData provides access to the FWIM's private data structure. 


5.3.4 FWIMPollInterruptsProc 

FWIMPollInterruptsProcis called by the FireWire services to initialize the FWIM. 

typedef OSStatus (FWIMPollInterruptsProc) ( 

FWIMPollInterruptsParamsPtr pFWIMPollInterruptsParams); 

<--> pFWIMPollInterruptsParams Pointer to parameter block. 

--> fwi mSpeci fi cData Private data used by FWIM. 

This is the value returned by 

FWIMIni ti al i zeProc. 
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--> fwimID Reference to target FWIM. 

--> fwimReg Entry ID Reference to FWIM's entry in the 

Name Registry. 


DESCRIPTION 

FWIMPol 1 InterruptsProc is called by the FireWire driver family expert to ask the 
FWIM to poll for pending interrupts. The parameter fwi mSpeci f i cData provides 
access to the FWIM's private data structure. FWIMPol 1 InterruptsProc may be 
called at any execution level. 

Synchronous requests may be sent to a FWIM while interrupts are disabled. In 
this case, the FireWire services calls FWIMPol 1 InterruptsProc to let the FWIM 
process interrupt events and complete any requests. 


5.3.5 FWlMCommandProc 

The FireWire services send commands to the FWIM by calling one of the 
command procs in the FWIM's dispatch table. The parameters to these 
commands follow the parameters for the generic FWlMCommandProc. 

OSStatusFWIMCommandProc ( 

FWIMCommandParamsPtr pFWIMCommandParams, 

UInt32 *pCommandAcceptance); 


<--> pFWIMCommandParams 

pNextFWIMCommandParams 

--> commandType 

--> fwimID 

--> fwimSpecificData 

--> commandFlags 

status 


Pointer to parameter block. 

Link to next command parameters 
in command queue. This link is 
set by the FireWire services; 
FWIMs should not use it 

Type of command being sent 
to the FWIM. 

Reference to target FWIM. 

FWIM's private data. This is 
the value returned from 
FWIMInitializeProc. 

Flags controlling the 

execution of the command. 

Current status of this command. Set 
by FireWire services; should 
not be modified by the FWIM. 
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--> fwimCommandID 


completionProc 


completionProcData 
<-- pCommandAcceptance 


Reference to this command. 

This is used in calls to 
FWIMCommandlsComplete. 
Procedure to call upon completion 
of command. FireWire services 
will take care of calling the 
completion procedure 
Data to be used by compl eti onProc. 
Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

FWIMInterface is called by the FireWire driver family software to send 
commands to the FWIM. It is used for a variety of purposes, such as setting up 
and running isochronous ports and handling read and write transactions. 
Typically, the command parameters are not of the generic type shown earlier 
but have additional parameters that further specify the command being sent. 
The various types of commands are detailed below. 

FWIMCommandProc is the generic version of the various command procedures 
detailed below. The commandType is set to the command selector constant. The 
fwi ml D is the ID used to reference the FWIM receiving the command. The 
fwi mSpeci ftcData is set to the parameter returned from the FWIMIni ti al i zeProc; 
typically, when the FWIM receives a command, it will retrieve a pointer to its 
private data record from fwimSpeci fi cData. The commandFl ags are set to control 
the execution of the command. Some of these flags are used only by the 
FireWire services. Currently, there are no defined flags that the FWIM must 
check. The fwi mCommandID is used as a reference to the command being issued to 
the FWIM. FWIMs use the fwimCommandID to tell the FireWire services that the 
issued command has been completed by passing it into a call to 
FWIMCommandlsCompl ete. 

When the FireWire services issue a command to the FWIM, the 
FWIMCommandProc does not need to complete the command before returning to 
the FireWire services. This allows for asynchronous operation of the various 
FWIM commands. When the issued command has been completed, the FWIM 
must call FWIMCommandlsCompl ete. 

The pCommandAcceptance parameter is set by the FWIM when it receives a 
command from the FireWire services. If the FWIM sets this parameter to 
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kFWIMCommandAcceptNoMore, it indicates that it can process the given command 
but cannot process any more until it completes a command by calling 
FWIMCorrrniandlsCompl ete. If the FWIM sets the parameter to 
kFWIMCommandAcceptMore, it indicates that it can process the given command and 
can process more commands. If the FWIM sets the parameter to 
kFWIMCommandRejected, it indicates that it cannot process the command now but 
may be able to after it completes a command by calling FWIMCommandlsCompl ete. 

This mechanism allows a FWIM to process more than one command at a time. 
If a FWIM is not processing a command, it should not return 
kFWIMCommandRejected when given a new command. 

While a FWIM may have multiple outstanding commands at one time, the 
FireWire services will ensure that calls made to the FWIM are serialized. Thus, 
when one of the entry points in the FWIM's dispatch table is called, no more 
calls will be made to the FWIM until the first call returns (either completed or 
not completed). In addition, FWIMProcessCompl eti onProcs and 
FWDeferredTaskProcs run by a FWIM will all be serialized with respect to each 
other and the dispatch table entry points. However, calls to different FWIMs 
may not necessarily be serialized with respect to each other. 

Depending upon the type of command being issued, a FWIM command proc 
may be called at nontask level. 


5.3.5.1 FWIMSendLinkOnPacketProc 

The FireWire services use the fwimSendLi nkOnPacketProc command to send a 
link-on physical layer (phy) packet to a remote node. 


typedef OSStatus (FWIMSendPhyPacketProc) ( 

FWIMSendPhyPacketParamsPtr pFWIMSendPhyPacket Pa rams, 

UInt32 *pCommandAcceptance); 


<-->p FWIMSendPhyPacketParams 
--> commandType 
--> generation 

--> buffer 

--> length 

<-- pCommandAcceptance 


Pointer to parameter block. 

kFWIMSendLinkOnPacket. 

Generation value of the 

topology map that the phy 
packet was constructed with. 

Buffer with phy packet data. 

Length of phy packet data. 

Value returned specifying 
acceptance of current and 
future commands. 
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DESCRIPTION 

The fwimSendLi nkOnPacketProc command is used by the FireWire services to 
turn on the link layer of a remote node. The data in butf er will be the first 
quadlet of a properly formatted link-on packet. The FWIM is responsible for 
generating the bit-inverted second quadlet. 

The link-on packet in buffer will contain a phy ID that is valid only for the 
topology map generation value specified in generation. The FWIM must check 
its current generation value; if it doesn't match the given generation value, the 
FWIM must call FWIMCommandlsCompl ete with a status of busReconf i guredErr. 

The length field will always be equal to 4. 

This command may be issued at nontask levels. 


5.3.5.2 FWIMSendPhyConfigurationPacketProc 

The FireWire services use the fwi mSendPhyConf i gurati onPacketProc command 
to send a phy configuration packet to all nodes. 


typedef OSStatus (FWIMSendPhyPacketProc) ( 

FWIMSendPhyPacketParamsPtr pFWIMSendPhyPacketParams, 

UInt32 *pCommandAcceptance); 


<--> pFWIMSendPhyPacketParams 
--> commandType 
--> generation 

--> buffer 

--> length 

<-- pCommandAcceptance 


Pointer to parameter block. 

kFWIMSendPhyConfigurationPacket. 

Generation value of the topology 
map that the phy packet was 
constructed with. 

Buffer with phy packet data. 

Length of phy packet data. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

The fwi mSendPhyConf i gurati onPacketProc command is used by the FireWire 
services to configure all the nodes on the FireWire bus. The data in buffer will 
be the first quadlet of a properly formatted phy configuration packet. The 
FWIM is responsible for generating the bit-inverted second quadlet. 

The phy configuration packet in buffer will contain a phy ID that is valid only 
for the topology map generation value specified in gene rati on. The FWIM must 


94 


5.3 Writing FireWire Interface Modules 



CHAPTER 5 


FireWire Interface Module Architecture 


check its current generation value; if it doesn't match the given generation 
value, the FWIM must call FWIMCommandlsCompl ete with a status of 

busReconfiguredErr. 

The length field will always be equal to 4. 

This command may be issued at nontask levels. 


5.3.5.3 FWIMReadProc 

The FireWire services use the fwimReadProc command to perform a read 
transaction on the FireWire bus associated with a given FWIM. 


typedef OSStatus (FWIMAsync 

FWIMAsynchCommandParamsPtr 
UInt32 

<--> pFWIMAsynchCommandParams 


--> 

commandType 

--> 

timeout 

--> 

generation 

--> 

buffer 

--> 

numRetries 

--> 

speed 

--> 

addressHi , 

--> 

1ength 


<-- pCommandAcceptance 


ransactionProc) ( 

pFWIMAsynchCommandParams, 
*pCommandAcceptance); 

Pointer to parameter block. 

kFWIMRead. 

Split transaction timeout period. 

Generation value of topology map 
used to generate target address. 

Pointer to buffer to read into. 

Number of times to retry transaction. 

Transmission speed to send packet. 

64-bit address destination of 
read transaction. 

Length of read transaction. 

Value returned specifying acceptance 
of current and future commands. 


hT 


DESCRIPTION 

The fwimReadProc command instructs the FWIM to send a read request for 
length bytes from the address specified by addressHi and addressLo across its 
FireWire bus, and to wait for the response. The FWIM copies the response 
payload into buffer if the transaction was successful. 

If the target node returns a busy acknowledge, the FWIM retries the transaction 

numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retry Exceeded Err. 
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If the target node returns ack_pendi ng but no response packet is received within 
the time period specified by ti meout, the FWIM should call 

FWIMCommandlsCompl ete with a status value of timeoutErr. 

If the given generation value is out of date, the FWIM should call 

FWIMCommandlsCompl ete with a status value of busReconfi guredErr. 

This command may be issued at nontask levels. 


5.3.5.4 FWIMReadResponseProc 

The FireWire services use the fwi mReadResponseProc command to send a read 
response packet on the FireWire bus associated with a given FWIM 

typedef OSStatus (FWIMSendAsynchResponsePacketProc) ( 

FWIMAsynchResponseCommandPa ramsPtr pFWIMAsynchResponseCommandParams, 
UInt32 *pCommandAcceptance); 


<--> pFWIMAsynchResponseCommandPc 
--> commandType 

--> timeout 

--> generation 

--> buffer 

--> numRetries 

--> speed 

--> transactionDescriptor 

--> destinationlD 

--> responseDataHi , response 

--> length 

--> extendedTCode 

<-- pCommandAcceptance 


rams Pointer to parameter block. 

kFWIMReadResponse. 

Time before which the 

response must be sent. 

Bus generation value for which 
response is valid. 

Buffer with response data. 

Number of times to retry 
transaction. 

Speed to transmit response. 

Transaction descriptor for 
response; includes 
transaction label. 

Node ID of the target of the 
response. 

ata Lo Response header data. 

Amount of response data. 

Extended transaction code for 
response. 

Value returned specifying 
acceptance of current 
and future commands. 
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DESCRIPTION 

The fwimReadResponseProc command instructs the FWIM to send a read 
response packet of 1 ength bytes to the node specified by desti nati onID. The 
FWIM copies the contents of buffer into the packet payload. 

The transacti onDescri ptor field contains the transaction label to use for the 
response packet located at kFWTransacti onDescri ptorTLabel, which is the same 
location as in the raw FireWire response packet. 

The responseDataHi field contains the response code to send in the response 
packet located at kFWResponseDataRCode, which is the same location as in the 
raw FireWire response packet. 

If the target node returns a busy acknowledge, the FWIM retries the response 
numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retry Exceeded Err. If the response packet cannot be 
delivered before the time specified by ti meout, the FWIM should call 

FWIMCommandlsCompl ete with a status value of timeout Err. 

If the generation value of the response specified by generation is no longer 
valid, the FWIM should call FWIMCommandlsCompl ete with a status value of 

busReconfiguredErr. 

This command may be issued at nontask levels. 


5.3.5.5 FWIMWriteProc 

The FireWire services use the fwimWri teProc command to perform a write 
transaction on the FireWire bus associated with a given FWIM. 


typedef OSStatus (FWIMAsync 

FWIMAsynchCommandParamsPtr 
UInt32 

<--> pFWIMAsynchCommandParams 
--> commandType 
--> timeout 

--> generation 

--> buffer 

--> numRetries 

--> speed 

--> addressHi , addressLo 


ransactionProc) ( 

pFWIMAsynchCommandParams, 
*pCommandAcceptance); 

Pointer to parameter block. 

kFWIMWri te. 

Split transaction timeout period. 

Generation value of topology map 
used to generate target address. 

Pointer to buffer to write into. 

Number of times to retry transaction. 

Transmission speed to send packet. 

64-bit address destination of 
write transaction. 


hT 
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--> length 
<-- pCommandAcceptance 


Length of write transaction. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

The fwi mWri teProc command instructs the FWIM to send a write request for 
1 ength bytes to the address specified by addressHi and addressLo across its 
FireWire bus, and to wait for the response or acknowledgement. The FWIM 
copies buffer into the request payload. 

If the target node returns a busy acknowledge, the FWIM retries the transaction 

numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retryExceededErr. 

If the target node returns ack_pendi ng but no response packet is received within 
the time period specified by ti meout, the FWIM should call 

FWIMCommandlsCompl ete with a status value of timeoutErr. 

If the given generation value is out of date, the FWIM should call 

FWIMCommandlsCompl ete with a status value of busReconfi guredErr. 

This command may be issued at nontask levels. 


5.3.5.6 FWIMWriteResponseProc 

The FireWire services use the fwi mWri teResponseProc command to send a write 
response packet on the FireWire bus associated with a given FWIM. 

typedef OSStatus (FWIMSendAsynchResponsePacketProc) ( 

FWIMAsynchResponseCommandPa ramsPtr pFWIMAsynchResponseCommandParams, 
UInt32 *pCommandAcceptance); 


<- - > pFWIMAsynchResponseCommandPa rams 
--> commandType 
--> timeout 

--> generation 

--> numRetries 

--> speed 


Pointer to parameter block. 

k FWI MWri te Response. 

Time before which the 

response must be sent. 

Bus generation value for 
which response is valid. 

Number of times to retry 
transaction. 

Speed to transmit response. 
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--> 

transactionDescriptor 

Transaction descriptor for 
response. Includes 
transaction label. 

--> 

destination ID 

Node ID of the target of the 
response. 

--> 

responseDatatli , responseData Lo 

Response header data. 

--> 

extendedTCode 

Extended transaction code for 
response. 


pCommandAcceptance 

Value returned specifying 


acceptance of current 
and future commands. 


DESCRIPTION 

The fwi mWri teResponseProc command instructs the FWIM to send a write 
response packet to the node specified by desti nati onID. The write response 
packet has no payload. 

The transacti onDescri ptor field contains the transaction label to use for the 
response packet located at kFWTransacti onDescri ptorTLabel, which is the same 
location as in the raw FireWire response packet. 

The responseDataHi field contains the response code to send in the response 
packet located at kFWResponseDataRCode, which is the same location as in the 
raw FireWire response packet. 

If the target node returns a busy acknowledge, the FWIM retries the response 

numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retry Exceeded Err. 

If the response packet cannot be delivered before the time specified by ti meout, 
the FWIM should call FWIMCommandlsCompl ete with a status value of timeoutErr. 

If the generation value of the response specified by generation is no longer 
valid, the FWIM should call FWIMCommandlsCompl ete with a status value of 

busReconfiguredErr. 

This command may be issued at nontask levels. 


5.3.5.7 FWIMLockProc 

The FireWire services use the fwimLockProc command to perform a lock 
transaction on the FireWire bus associated with a given FWIM. 
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typedef OSStatus (FWIMAsynchTransactionProc) ( 

FWIMAsynchCommandPa ramsPtr pFWIMAsynchCommandParams, 

UInt32 *pCommandAcceptance); 


<--> 

pFWIMAsynchCommandPa rams 

Pointer to parameter block. 

--> 

commandType 

kFWIMLock. 

--> 

timeout 

Split transaction timeout period. 

--> 

generation 

Generation value of topology map 
used to generate target address. 

--> 

buffer 

Pointer to buffer with lock data. 

--> 

numRetries 

Number of times to retry 
transaction. 

--> 

speed 

Transmission speed to send packet. 

--> 

addresstli , addressLo 

64-bit address destination 
of lock transaction. 

--> 

1ength 

Length of lock transaction. 

--> 

extendedTCode 

Extended transaction code 
indicating the type of lock 
transaction to perform. 

<-- 

pCommandAcceptance 

Value returned specifying 


acceptance of current and 
future commands. 


DESCRIPTION 

The fwi mLockProc command instructs the FWIM to send a lock request for 
1 ength bytes to the address specified by addresstli and addressLo across its 
FireWire bus, and to wait for the response. The FWIM copies copies buffer into 
the request payload and the response payload into buffer if the transaction was 
successful. 

If the target node returns a busy acknowledge, the FWIM retries the transaction 

numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retryExceededErr. 

If the target node returns ack_pendi ng but no response packet is received within 
the time period specified by timeout, the FWIM should call 

FWIMCommandlsCompl ete with a status value of timeoutErr. 

If the given generation value is out of date, the FWIM should call 

FWIMCommandlsCompl ete with a status value of busReconfi guredErr. 

This command may be issued at nontask levels. 
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5.3.5.8 FWIMLockResponseProc 

The FireWire services use the fwimLockResponseProc command to send a lock 
response packet on the FireWire bus associated with a given FWIM 

typedef OSStatus (FWIMSendAsynchResponsePacketProc) ( 

FWIMAsynchResponseCommandParamsPtr pFWIMAsynchResponseCommandParams, 
UInt32 *pCommandAcceptance); 


<--> pFWIMAsynchResponseCommandP 
--> commandType 

--> timeout 

--> generation 

--> buffer 

--> numRetries 

--> speed 

--> transactionDescriptor 

--> destination ID 

--> responseDataHi , response 

--> length 

--> extendedTCode 

<-- pCommandAcceptance 


ams Pointer to parameter block. 

kFWIMLockResponse. 

Time before which the 

response must be sent. 

Bus generation value for which 
response is valid. 

Buffer with response data. 

Number of times to retry 
transaction. 

Speed to transmit response. 

Transaction descriptor for 
response. Includes 
transaction label. 

Node ID of the target of the 
response. 

D a t a L o Response header data. 

Amount of response data. 

Extended transaction code for 
response. 

Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

The fwi mLockResponseProc command instructs the FWIM to send a lock 
response packet of 1 ength bytes to the node specified by desti nati onID. The 
FWIM copies the contents of buffer into the packet payload. 

The transacti onDescri ptor field contains the transaction label to use for the 
response packet located at kFWTransacti onDescri ptorTLabel, which is the same 
location as in the raw FireWire response packet. 
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The responseDataHi field contains the response code to send in the response 
packet located at kFWResponseDataRCode, which is the same location as in the 
raw FireWire response packet. 

If the target node returns a busy acknowledge, the FWIM retries the response 

numRetri es times; if this fails, the FWIM should call FWIMCommandlsCompl ete 
with a status value of retryExceededErr. 

If the response packet cannot be delivered before the time specified by timeout, 
the FWIM should call FWIMCommandlsCompl ete with a status value of ti meoutErr. 

If the generation value of the response specified by generati on is no longer 
valid, the FWIM should call FWIMCommandlsCompl ete with a status value of 

bus Reconfigured Err. 

This command may be issued at nontask levels. 


5.3.5.9 FWIMAIIocatelsochPortProc 

The FireWire services use the fwimAl 1 ocatelsochPortProc command to allocate 
an isochronous port on the FireWire bus associated with a given FWIM. 

typedef OSStatus (FWIMAIIocatelsochPortProc) ( 


FWIMAllocatelsochPortParamsPtr 

UInt32 

<--> pFWIMAllocatelsochPortParams 
--> commandType 

<-- isochPortID 

--> dcIProgramID 

--> channelNum 

--> speed 

--> talking 


<-- pCommandAcceptance 


pFWIMAllocatelsochPortParams, 

*pCommandAcceptance); 

Pointer to parameter block. 

kFWIMAllocatelsochPort. 

Reference to this port for use in 
subsequent port commands. 

ID of DCL program to use with this 
port. 

Isochronous channel number that 
port is to talk to or listen from. 

Speed that port is to run at. 

If fal se, the port should be set up 
for listening; otherwise, it 
should be set up for talking. 

Value returned specifying 
acceptance of current and 
future commands. 
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DESCRIPTION 

The fwimAl locate I sochPortProc command is used to allocate an isochronous 
port for talking or listening on the bus associated with the given FWIM. The 
FWIM should do any preprocessing and allocation it needs to set up the 
isochronous buffers specified bydcIProgramID. The FWIM should set up a port 
for talking or listening as specified by the talking parameter. The port should 
operate at a speed specified by speed on a channel number specified by 
channel Num. The FWIM should create a reference to the allocated port and 
return it in isochPortID. 

If the FWIM cannot support the given speed or has no more isochronous ports 
available, it should send a status value of paramErr to FWIMCommandlsCompl ete. 

This command will be issued only at task level. 


5.3.5.10 FWIMReleaselsochPortProc 

The FireWire services use the fwimReleaselsochPortProc command to release all 
resources allocated for a given isochronous port. 


typedef OSStatus (FWIMReleaselsochPortProc) ( 

FWIMReleaselsochPortParamsPtr pFWIMReleaselsochPortParams, 

UInt32 *pCommandAcceptance); 


<--> pFWIMReleaselsochPortParams Pointer to parameter block. 


--> commandType 
--> isochPortID 
<-- pCommandAcceptance 


kFWIMReleaselsochPort. 

Reference to port to release. 
Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

The fwimReleaselsochPortProc command is used to release all resources 
allocated for the isochronous port specified by i sochPortID. The FWIM should 
deallocate all data structures and free up all hardware resources allocated for 
the given port. 

If the isochPortID value is invalid, the FWIM should send a status value of 

i rival idlsochPortIDErr to FWIMCommandlsCompl ete. 

This command will be issued only at task level. 
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5.3.5.11 FWIMStartlsochPortProc 

The FireWire services use the fwimStartlsochPortProc command to instruct a 
given isochronous port to begin talking or listening. 


typedef OSStatus (FWIMControl I 

FWIMIsochPortControlParamsPtr 
UInt32 

<--> pFWIMIsochPortControlParams 

--> commandType 

--> isochPortlD 

<-- pCommandAcceptance 


ochPortProc) ( 

pFWIMIsochPortControlParams, 
*pCommandAcceptance); 

Pointer to parameter block. 
kFWIMStartlsochPort. 
Reference to port to start. 
Value returned specifying 
acceptance of current and 
future commands. 


DESCRIPTION 

The fwimStartlsochPortProc command is used to instruct the isochronous port 
specified by i sochPortID to begin talking or listening as specified in the 

fwi mAl 1 ocatelsochPortProc command. 

If the i sochPortID value is invalid, the FWIM should send a status value of 

invalidlsochPortIDErrto FWIMCommandlsCompl ete. 

This command may be issued at nontask levels. 


5.3.5.12 FWIMStopIsochPortProc 

The FireWire services use the fwimStopIsochPortProc command to instruct a 
given isochronous port to stop talking or listening. 


typedef OSStatus (FWIMControlIsochPortProc) ( 

FWIMIsochPortControlParamsPtr pFWIMIsochPortControlParams, 

UInt32 *pCommandAcceptance); 


<--> pFWIMIsochPortControlParams 
--> commandType 
--> isochPortID 
<-- pCommandAcceptance 


Pointer to parameter block. 
kFWIMStopIsochPort. 

Reference to port to stop. 

Value returned specifying 
acceptance of current and future 
commands. 
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DESCRIPTION 

The fwimStopIsochPortProc command is used to instruct the isochronous port 
specified by isochPortIDto stop talking or listening as specified in the 

fwimAl 1 ocatelsochPortProc command. 

If the isochPortID value is invalid, the FWIM should send a status value of 

i rival idlsochPortIDErr to FWIMCommandlsCompl ete. 

This command may be issued at nontask levels. 


5.3.5.13 FWIMResetBusProc 

The FireWire services use the fwimResetBusProc command to initiate a bus reset 
across the FireWire bus associated with a given FWIM. 


typedef OSStatus 

FWIMCommandParamsPtr 

UInt32 


(FWIMCommandProc) ( 

pFWIMCommandParamsd, 
*pCommandAcceptance); 


<--> 

pFWIMCommandParams 

Pointer to parameter block. 

--> 

commandType 

kFWIMResetBus. 

<-- 

pCommandAcceptance 

Value returned specifying acceptance 


of current and future commands. 


DESCRIPTION 

The fwimResetBusProc command instructs the FWIM to initiate a bus reset 
across the FireWire bus. 

This command may be issued at nontask levels. 


5.3.5.14 FWIMSetContenderBitProc 

The FireWire services use the fwi mSetContenderBi tProc command to indicate to 
the rest of the bus its isochronous resource or bus management capability. 

typedef OSStatus (FWIMCommandProc) ( 

FWIMCommandParamsPtr pFWIMCommandParamsd, 

UInt32 *pCommandAcceptance); 
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<--> pFWIMCommandParams 
--> commandType 
<-- pCommandAcceptance 


Pointer to parameter block. 
kFWIMSetContenderBit. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

The fwi mSetContenderBi tProc command instructs the FWIM to indicate in its 
sel f ID packet on subsequent bus resets that the local node is capable of being 
the isochronous resource or bus manager. 

In some cases, the local host may wish to power down into a sleep state. Some 
systems may not be capable of performing isochronous resource or bus 
management tasks in this state. Thus, the fwi mSetContenderBi tProc and 
fwi mCl ea rContenderBi tProc FWIM commands are provided so that the local 
host may become the isochronous resource or bus manager only when it is 
capable of doing so. A FWIM should not indicate that the local node is capable 
of being the isochronous resource or bus manager until it is instructed to do so 
by the fwi mSetContenderBi tProc command (i.e., the power-on default should 
not indicate the capability). 

This command may be issued at nontask levels. 


5.3.5.15 FWlMClearContenderBitProc 

The FireWire services use the fwi mCl ea rContenderBi tProc command to indicate 
to the rest of the bus its lack of isochronous resource or bus management 
capability. 

typedef OSStatus (FWIMCommandProc) ( 


FWIMCommandParamsPtr 

pFWIMCommandPa ramsd, 

UInt32 

*pCommandAcceptance); 

<--> pFWIMCommandParams 

Pointer to parameter block. 

--> commandType 

kFWIMClea rContenderBi t. 

<-- pCommandAcceptance 

Value returned specifying acceptance of 
current and future commands. 
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DESCRIPTION 

The fwimClearContenderBitProc command instructs the FWIM to indicate in its 
sel f ID packet on subsequent bus resets that the local node is not capable of 
being the isochronous resource or bus manager. 

This command may be issued at nontask levels. 

5.3.5.16 FWIMEnableCycleMasterProc 

The FireWire services use the fwimEnableCycleMasterProc command to instruct 
the local node to start sending cycle-start packets. 

typedef OSStatus (FWIMCommandProc) ( 

FWIMCommandParamsPtr pFWIMCommandParamsd, 


UInt32 

*pCommandAcceptance); 

<--> 

pFWIMCommandParams 

Pointer to parameter block. 

--> 

commandType 

kFWIMEnableCycleMaster. 

<-- 

pCommandAcceptance 

Value returned specifying acceptance 


of current and future commands. 


DESCRIPTION 

The fwimEnableCycleMasterProc command instructs the FWIM to begin sending 
cycle-start packets. The FireWire services will issue this command only when it 
determines that the local host is the root node. However, software latencies 
may cause a bus reset to occur before this command has finished. Thus, the 
FWIM should recheck if the local node is the root before enabling itself as the 
cycle master. 

This command may be issued at nontask levels. 

5.3.5.17 FWlMDisableCycleMasterProc 

The FireWire services use the fwimDisableCycleMasterProc command to instruct 
the local node to stop sending cycle-start packets. 

typedef OSStatus (FWIMCommandProc) ( 

FWIMCommandParamsPtr pFWIMCommandParamsd, 

UIn132 *pCommandAcceptance); 
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<--> pFWIMCommandParams 
--> commandType 
<-- pCommandAcceptance 


Pointer to parameter block. 
kFWIMDi sabl eCycl eMaster. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

The fwi mDi sabl eCycl eMasterProc command instructs the FWIM to stop sending 
cycle-start packets. 

This command may be issued at nontask levels. 


5.3.5.18 FWIMSetRootHoldoffBitProc 

The FireWire services use the fwi mSetRootHol doffBi tProc command to set the 
root holdoff bit in the phy of the local node 

typedef OSStatus (FWIMCommandProc) ( 


FWIMCommandPa ramsPtr 

UInt32 

pFWIMCommandPa ramsd, 
*pCommandAcceptance); 

<--> pFWIMCommandParams 

--> commandType 

<-- pCommandAcceptance 

Pointer to parameter block. 

kFWIMSetRootHol doffBi t. 

Value returned specifying acceptance 


of current and future commands. 


DESCRIPTION 

The fwi mSetRootHol doffBi tProc command instructs the FWIM to set the root 
holdoff bit in its phy so that the local node will become root after subsequent 
bus resets. 

This command may be issued at nontask levels. 


5.3.5.19 FWlMClearRootHoldoffBitProc 

The FireWire services use the fwi mCl ea rRootHol doffBi tProc command to clear 
the root holdoff bit in the phy of the local node. 

typedef OSStatus (FWIMCommandProc) ( 

FWIMCommandParamsPtr pFWIMCommandParamsd, 

UInt32 *pCommandAcceptance); 
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<--> 

pFWIMCommandParams 

Pointer to parameter block. 

--> 

commandType 

kFWIMCI ear RootHoidoffBit. 

<-- 

pCommandAcceptance 

Value returned specifying acceptance 


of current and future commands. 


DESCRIPTION 

The fwi mCl ear Root Hoi doffBitProc command instructs the FWIM to clear the 
root holdoff bit in its phy so that the local node will not necessarily become 
root after subsequent bus resets. 

This command may be issued at nontask levels. 


5.3.5.20 FWlMGetUniquelDProc 

The FireWire services use the fwimGetUniquelDProc command to obtain a 
unique ID for the local node. 


typedef OSStatus (FWIMComman 

FWIMGetUniquelDParamsPtr 
UInt32 

<--> pFWIMCommandParams 

--> commandType 

<-- uniquelD 

<-- pCommandAcceptance 


dProc) ( 

pFWIMCommandParamsd, 
*pCommandAcceptance); 

Pointer to parameter block. 
kFWIMGetUni quelD. 

Unique ID of local node. 

Value returned specifying acceptance 
of current and future commands. 


DESCRIPTION 

The fwi mGetUni quelDProc command instructs the FWIM to return a unique ID 
for the local node. Typically, FireWire adapter cards will have a silicon serial 
number from which a 64-bit unique ID can be generated. The FWIM should 
return this 64-bit unique ID value generated from the silicon serial number on 
the adapter card. 

This command may be issued at nontask levels. 
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5.4 FireWire Interface Module Services 


5.4.1 FWlMCommandlsComplete 

When a FWIM has completed a command, it calls FWIMCommandlsCompl ete to 
notify the FireWire services that the command has been completed. 


OSStatus FWlMCommandlsComplete ( 


FWIMCommandlD 

OSStatus 

--> fwimCommandID 

--> commandStatus 


fwimCommandID 
commandStatus); 

ID given to FWIM in call to 

fwiminitializeProc. 

Final status of command. 


DESCRIPTION 

When a FWIM finishes executing a command, it notifies the FireWire services 
by calling FWIMCommandlsCompl ete. The FWIM specifies the completed command 
with the fwi mCommand ID that was passed to the FWIM when the FireWire 
services called FWIMInterface. The FWIM indicates the final status of the 
command in commandStatus. The FWIM may call FWIMCommandlsCompl ete in any 
environment except primary interrupt level. 


5.4.2 FWProcessBusReset 

When a FWIM detects that a FireWire bus reset has occurred, it calls 
FWProcessBusReset to notify the FireWire services of that event. 

OSStatus FWProcessBusReset ( 

FWIMID fwimlD); 

--> fwi ml D ID of FWIM making call. 
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DESCRIPTION 

When a FWIM detects a FireWire bus reset, it notifies the FireWire services 
using FWProcessBusReset. This causes the FireWire services to perform their bus 
reset tasks. 

Typically, a FireWire interface card controlled by a FWIM will generate an 
interrupt when a bus reset occurs; the FWIM will process this interrupt at 
primary interrupt level. The FWIM should immediately call FWProcessBusReset 
from that level because the FireWire services must be notified of FireWire bus 
resets as soon as possible. 

FWProcessBusReset must be called even if the FWIM was called to initiate the 
FireWire bus reset by a kFWIMResetBus command. Typically, a FireWire interface 
card will generate a FireWire bus reset interrupt even when the card has been 
programmed to initiate the FireWire bus reset. 


5.4.3 FWProcessReadRequest 

FWProcessReadRequest is used by a FWIM to process a received read request 
packet. 

OSStatus FWProcessReadRequest ( 

FWIMProcessAsynchParamsPtr pFWIMProcessAsynchParams); 


> 

pFWIMProcessAsynchParamsParams 

Pointer to parameter block. 

--> 

fwimID 

ID of FWIM making call. 

--> 

processFlags 

Flags used to control processing. 

<-- 

processStatus 

Final result of processing. 

--> 

completionProc 

Procedure to call upon completion 
of processing. 

--> 

completionProcData 

Data to be used by completionProc. 

--> 

timeStamp 

Time request packet was received. 

--> 

generation 

Topology generation for which 
packet was received. 

--> 

receiveBuffer 

Buffer with received asynchronous 
packet data. 

--> 

destination ID 

Node ID of destination of received 
asynchronous packet (may be 
ignored). 

--> 

transaction Descriptor 

Transaction descriptor for request. 
Includes transaction label. 

FireWire Interface Module Services 
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--> sourcelD 

--> addressHi , addressLo 

--> length 

--> extendedTCode 

--> transactionStatus 


Node ID of source of the read 
request. 

64-bit address destination of read 
request. 

Length of read request. 

Extended transaction code of 

received asynchronous packet. 

Transaction status for request 
packet. Includes ackCode and 
speed. 


DESCRIPTION 

When a FWIM receives a read request packet from a remote node, it uses 
FWProcessReadRequest to process the read request. FWProcessReadRequest will 
check the target address of the read and, if it's a valid address, route it to the 
owner of the address. The FWIM does not need to fill in d e s t i n a t i o n ID; this 
parameter is provided for the convenience of many FireWire DMA engines. 

The transacti onDescriptor field contains the transaction label of the received 
packet located at kFWTransacti onDescri ptorTLabel, which is the same location 
as in the raw FireWire request packet. 

The transacti onStatus field contains the speed of the received packet and the 
acknowledgement sent in response to the packet. These values are located at 

kFWT ransactionStatusSpeed and kFWT ransactionStatusAckCode. 

The FWIM calls FWProcessReadRequest asynchronously and must provide a 
completion procedure to be called when the processing has finished. When the 
processing has finished, the completion procedure will be called, and the 
FWIM may reuse the parameter record and all buffers passed in. The FireWire 
services will send a read response packet if necessary by calling the FWIM's 
fwimReadResponseProc. 

Typically, a FWIM will allocate a number of FWIMProcessAsynchParams records to 
process received asynchronous packets. The FWIM may have as many 
FWProcessReadRequest calls pending as it has FWIMProcessAsynchParams records. 
When the FWIM runs out of resources (FWIMProcessAsynchParams records and 
packet buffers) to process received packets, it should start sending busy 
acknowledgements until those resources are released. 

This routine and the completion procedure may be called in any environment 
except primary interrupt level. 
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5.4.4 FWProcessWriteRequest 

FWProcessWri teRequest is used by a FWIM to process a received write request 
packet. 

OSStatus FWProcessReadRequest ( 

FWIMProcessAsynchParamsPtr pFWIMProcessAsynchParams); 

<--> pFWIMProcessAsynchParamsParams Pointer to parameter block. 


--> 

fwimID 

ID of FWIM making call. 

--> 

processFlags 

Flags used to control processing. 

<-- 

processStatus 

Final result of processing. 

--> 

completionProc 

Procedure to call upon completion 
of processing. 

--> 

completionProcData 

Data to be used by compl eti onProc. 

--> 

timeStamp 

Time that request packet was 
received. 

--> 

generation 

Topology generation for which 
packet was received. 

--> 

receiveBuffer 

Buffer with received asynchronous 
packet data. 

--> 

destination ID 

Node ID of destination of received 
asynchronous packet (may be 
ignored). 

--> 

transactionDescriptor 

Transaction descriptor for request. 
Includes transaction label. 

--> 

sourcelD 

Node ID of source of the write 
request. 

--> 

addressHi , addressLo 

64-bit address destination of write 
request. 

--> 

1ength 

Length of write request. 

--> 

extendedTCode 

Extended transaction code of 

received asynchronous packet. 

--> 

transactionStatus 

Transaction status for request 
packet. Includes ackCode and 


speed. 


When a FWIM receives a write request packet from a remote node, it uses 

FWProcessWri teRequest to process the write request. FWProcessWri teRequest will 
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check the target address of the write and, if it's a valid address, route it to the 
owner of the address. The FWIM does not need to fill in desti nati on ID; this 
parameter is provided for the convenience of many FireWire DMA engines. 

The transact! onDescri ptor field contains the transaction label of the received 
packet located at kFWTransacti onDescri ptorTLabel, which is the same location 
as in the raw FireWire request packet. 

The transacti onStatus field contains the speed of the received packet and the 
acknowledgement sent in response to the packet. These values are located at 

kFWTransactionStatusSpeed and kFWTransactionStatusAckCode. 

The FWIM calls FWProcessWrite Re quest asynchronously and must provide a 
completion procedure to be called when the processing has finished. When the 
processing has finished, the completion procedure will be called, and the 
FWIM may reuse the parameter record and all buffers passed in. The FireWire 
services will send a write response packet if necessary by calling the FWIM's 
fwi mWri teResponseProc. 

Typically, a FWIM will allocate a number of FWIMProcessAsynchParams records to 
process received asynchronous packets. The FWIM may have as many 
FWProcessWri teRequest calls pending as it has FWIMProcessAsynchParams records. 
When the FWIM runs out of resources (FWIMProcessAsynchPa rams records and 
packet buffers) to process received packets, it should start sending busy 
acknowledgements until those resources are released. 

This routine and the completion procedure may be called in any environment 
except primary interrupt level. 


5.4.5 FWProcessLockRequest 

FWProcessLockRequest is used by a FWIM to process a received lock request 
packet 

OSStatus FWProcessLockRequest ( 

FWIMProcessAsynchParamsPtr pFWIMProcessAsynchParams); 


<- - > pFWIMProcessAsynchPa rams Pa rams 

--> fwimlD 

--> processFlags 

<-- processStatus 

--> completionProc 


Pointer to parameter block. 

ID of FWIM making call. 

Flags used to control processing. 
Final result of processing. 
Procedure to call upon completion 
of processing. 
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--> 

completionProcData 

Data to be used by compl eti onProc. 

--> 

timeStamp 

Time that request packet was 
received. 

--> 

generation 

Topology generation for which 
packet was received. 

--> 

receiveBuffer 

Buffer with received asynchronous 
packet data. 

--> 

destination ID 

Node ID of destination of received 
asynchronous packet (may be 
ignored). 

--> 

transactionDescriptor 

Transaction descriptor for request. 

--> 

sourcelD 

Node ID of source of the lock 
request. 

--> 

addressHi , addressLo 

64-bit address destination of lock 
request. 

--> 

1ength 

Length of lock request. 

--> 

extendedTCode 

Extended transaction code of 

received asynchronous packet. 

--> 

transactionStatus 

Transaction status for request 
packet. Includes ackCode and 


speed. 


DESCRIPTION 

When a FWIM receives a lock request packet from a remote node, it uses 
FWProcessLockRequest to process the lock request. FWProcessLockRequest will 
check the target address of the lock and, if it's a valid address, route it to the 
owner of the address. The FWIM does not need to fill in desti nation ID; this 
parameter is provided for the convenience of many FireWire DMA engines. 

The transacti onDescri ptor field contains the transaction label of the received 
packet located at kFWTransacti onDescri ptorTLabel, which is the same location 
as in the raw FireWire request packet. 

The transacti onStatus field contains the speed of the received packet and the 
acknowledgement sent in response to the packet. These values are located at 

kFWT ransactionStatusSpeed and kFWT ransactionStatusAckCode. 

The FWIM calls FWProcessLockRequest asynchronously and must provide a 
completion procedure to be called when the processing has finished. When the 
processing has finished, the completion procedure will be called, and the 
FWIM may reuse the parameter record and all buffers passed in. The FireWire 
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services will send a lock response packet if necessary by calling the FWIM's 

fwimLockResponseProc. 

Typically, a FWIM will allocate a number of FWIMProcessAsynchParams records to 
process received asynchronous packets. The FWIM may have as many 
FWProcess LockRequest calls pending as it has FWIMProcessAsynchParams records. 
When the FWIM runs out of resources (FWIMProcessAsynchPa rams records and 
packet buffers) to process received packets, it should start sending busy 
acknowledgements until those resources are released. 

This routine and the completion procedure may be called in any environment 
except primary interrupt level. 


5.4.6 FWProcessSelfIDs 

FWProcessSel f IDs is used by a FWIM to process a received sel f ID packet. 

OSStatus FWProcessSelfIDs ( 

FWIMProcessSelfIDsParamsPtr pFWIMProcessSelfIDsParams); 


<--> pFWIMProcessSelfIDsParamsParams 
--> fwimlD 

--> processFlags 

<-- processStatus 

--> completionProc 

--> completionProcData 

<-- generation 

- -> pSel f IDLi st 

- -> sel f IDLi stSi ze 

--> pLocalSelfID 

--> 1ocalSelfIDSize 

--> processSelfIDsFlags 


Pointer to parameter block. 

ID of FWIM making call. 

Flags used to control 
processing. 

Final result of processing. 
Procedure to call upon 

completion of processing. 
Data to be used by 
compl eti onProc. 

Returned topology generation 
value. 

Pointer to list of received 

sel f I Ds. 

Size of sel f ID list. 

Pointer to list of local sel f ID. 
Size of local sel f ID. 

Flags controlling processing of 

sel f I Ds. 
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DESCRIPTION 

When a FWIM receives a sel f ID packet after a bus reset, it uses 
FWProcessSelfIDs to process the sel f ID list. The FireWire services will create a 
topology map from the information provided to FWProcessSelfIDs and return 
the generation value set in the topology map. The FWIM should use the 
generation value returned by FWProcessSel f I Ds when validating FWIM 
commands that specify generation values (e.g., fwi mReadProc commands). 

The FWIM may call FWProcessSel fIDs synchronously because it is not possible 
to send busy acknowledgments to sel f ID packets. 

Typically, a FWIM will receive a sel f ID packet with the sel f I Ds and inverted 
sel f IDs sent from all remote nodes. The pSelfIDList parameter points to the 
beginning of this packet, and the selfIDListSize parameter specifies the size of 
the packet. The FWIM will generate its own sel f ID and specify a pointer to its 

sel f ID in pLocal Sel f ID and its sel f ID size in 1 ocal Sel flDSi ze. 

The processSelfIDsFlags parameter is used to control the processing of the 
sel f IDs list and the local sel f ID. Currently, there are no defined flags. 

This routine and the completion procedure may be called in any environment 
except primary interrupt level. 


5.4.7 FWCreateDeferredTask 

FWCreateDeferredTask may be used to create a task that may be scheduled 
within any execution environment including primary interrupt level. 


OSStatusF WCreateDeferredTask 

FWDeferredTaskID 
FWDeferredTaskProcPtr 
voi d 


( 

*pFWDeferredTaskID, 
fwDeferredTaskProc, 
*paraml); 


<-- 

pFWDeferredTaskID 

Returned reference to newly created 
deferred task. 

--> 

fwDeferredTaskProc 

Proc to call when deferred task is 
executed. 

--> 

paraml 

First parameter to pass to 

fwDeferredTaskProc. 
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DESCRIPTION 

FWIMs may use FireWire deferred tasks to defer execution to a different 
execution environment. These deferred tasks are created by calling 

FWCreateDeferredTask. 

Typically, a FWIM will use deferred tasks to complete some processing 
initiated by a hardware interrupt. For instance, a FWIM's interrupt handler 
may get called when a asynchronous request packet is received. The FWIM's 
primary interrupt handler will clear the interrupt source register and will 
schedule a deferred task to run to process the received packet and possibly call 
a FireWire process service (e.g., FWProcessReadRequest). 

When the deferred task is executed, the procedure passed in the 
fwDeferredTaskProc parameter will be called and will be passed two 
parameters. The first parameter is the pa rami passed to FWCreateDeferredTask. 
The second parameter is the param2 passed in to FWSchedul eDeferredTask when 
the deferred task is scheduled for execution. 

FWCreateDeferredTask may be called only at task level. 


5.4.8 FWDisposeDeferredTask 

FWDi sposeDeferredTask disposes of the given deferred task and all resources 
allocated for it. 

OSStatus FWDisposeDeferredTask ( 

FWDeferredTaskID fwDeferredTaskID); 

--> fwDeferredTaskID Reference to deferred task to dispose of. 


DESCRIPTION 

FWDi sposeDeferredTask is used to dispose of a deferred task that is no longer 
needed. It may be called only at task level. 


5.4.9 FWScheduleDeferredTask 

FWSchedul eDeferredTask schedules a deferred task to be executed at FireWire 
deferred task time. 
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OSStatus FWScheduleDeferredTask ( 

FWDeferredTaskID fwDeferredTasklD, 

void *param2); 


--> fwDeferredTaskID Reference to deferred task to dispose of. 

- - > p a r a m 2 Second parameter to pass to 

fwDeferredTaskProc specified in 
FWCreateDeferredTask. 


DESCRIPTION 

FWScheduleDeferredTask is used to schedule a deferred task to be executed at 
FireWire deferred task time. FWSchedul eDeferredTask may be called multiple 
times for the same fwDeferredTaskID. However, once FWSchedul eDeferredTask is 
called for a particular fwDeferredTaskID, it should not be called again until the 
deferred task has been executed. 

All deferred tasks are run at the same execution level (FireWire deferred task 
level) and are serialized with respect to each other. All FireWire services that 
may be called at nontask level may be called at FireWire deferred task level. 

FWScheduleDeferredTask may be called in any execution environment including 
primary interrupt level. 
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A FireWire service command object is an opaque reference to a collection of 
parameters that control a particular set of FireWire services such as 
asynchronous packet transactions or FCP transactions. This chapter describes 
the interface that the Mac OS provides for command objects. 


6.1 Structures, Data Types, and Constants 


6.1.1 Command Object Types 


typedef Kernel ID 

typedef Kernel ID 

typedef void 

FWCommandObjectlD 

OSStatus 

UInt32 

typedef FWCommandCompletionProc 

FWReferencelD 
FWCommandObjectIDO 
FWCommandCompletionProc 


FWReferencelD; 

FWCommandObjectlD; 

(FWCommandCompletionProc) ( 
fwCommandObjectID, 
commandStatus, 
completionProcData); 

*FWCommandCompletionProcPtr; 


Generic reference to FireWire entity. 
Object ID used with FireWire services. 
Routine to call upon completion of service, 


6.1.2 Command Object Constants 

The following constant specifies the only flag for a FireWire service call: 
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enum 


kFWCommandSyncFlag 

} ; 


= (1 « 0 ) 


kFWCommandSyncFl ag Specifies that the service call should not 

return until the command has finished. 

The following constants specify the various types of FireWire service calls: 

enum 


kFWBasicCommandObj ectType 
kFWAsynchCommandOj bectType 
kFWIsochChannelCommandObj ectType 
kFWIsochPortCommandObj ectType 
kFWFCPCommandObjectType 

); 

kFWBasicCommandObj ectType 

kFWAsynchCommandObj ectType 

kFWIsochChannelCommandObj ectType 
kFWIsochPortCommandObj ectType 
kFWFCPCommandObj ectType 


= 1 , 

= 2 . 

= 3. 

= 4, 

= 5 

Type of command object for 
simple services that require 
only the basic parameter set. 

Type of command object for 

asynchronous packet FireWire 
transaction services. 

Type of command object for 

isochronous channel services. 

Type of command object for 
isochronous port services. 

Type of command object for 

Function Control Protocol (FCP) 
transaction services. 


6.2 FireWire Service Command Object Overview 


The FireWire driver family provides many complex services that take 
numerous parameters. Typically, these services involve routing requests to 
other drivers or FWIMs and may be performed asynchronously. A simple, 
immediate parameter calling convention (i.e., FWServi ce ( paraml , par ami, 
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param3 ,...)) is not sufficient for these services. Thus, the FireWire driver family 
uses FireWire service command objects. 

A FireWire service command object is an opaque reference to a collection of 
parameters that control a particular set of FireWire services. Each of these 
FireWire services share the following common set of basic parameters: 

corrrniandObjectType 
commandType 
fwReferencelD 
commandFlags 
commandStatus 
completionProc 
completionProcData 

In addition to these basic parameters, each service may specify additional 
parameters specific to that service's class. These services will not use the basic 
command object type, but will use another type specific to that service's class. 
For example, to perform a FireWire write transaction a driver would use a 
command object of type kFWAsynchCommandObjectType, which would also specify 
parameters such as the destination address, write buffer, and transaction size in 
addition to the basic parameters. 

All of the parameters are accessed through set and get routine calls. Some 
parameters may have only a set or only a get call. For instance, the 
commandStatus parameter is an output-only parameter and therefore has no set 
call. Most of the service classes provide set and get routine calls that cover all of 
the classes parameters. Thus, drivers can usually set up all of a command 
object's parameters with one or two routine calls. 

Each class of services include a command object allocation routine that 
implicitly sets the command object type. Thus, drivers should not have to set 
command object types. In addition, the command type parameter will be set 
when a service routine is called, so drivers should not have to set the command 
type either. 
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6.3 FireWire Service Command Object Routines 


6.3.1 FWAIIocateFWCommandObject 

FWAllocateFWCommandObject creates a basic FireWire service command 
object. 

OSStatus FWAllocateFWCommandObject ( 

FWCommandObjectID *pFWCommandObjectID); 

< - - pFWCommandObj ectl D Returned reference to created basic 

FireWire service command object. 


DESCRIPTION 

FWA11 ocateFWCommandObject creates a FireWire service command object for the 
basic class of FireWire services. It sets most of the parameters to default values. 
The command FI ags parameter defaults to 0, which indicates that the service call 
will complete asynchronously. The compl eti onProc parameter will default to 
ni 1, so no completion proc will be called; thus, the compl eti onProcData 
parameter will be unused (it will default to 0). The only parameter that has no 
meaningful default value is the fwReferencelD; this parameter must be set 
before any FireWire service can be called with the created command object. 

All of the default values may be overridden by the routines below. 


6.3.2 FWDeallocateFWCommandObject 

FWDeallocateFWCommandObject deallocates all resources allocated for the 
given command object. 

OSStatus FWDeallocateFWCommandObject ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object to deallocate. 
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DESCRIPTION 

FWDeal 1 ocateFWCommandObject deallocates all resources allocated for the given 
command object. This routine may be used for all command object types. 
Because each FireWire serivce class object allocation routine sets the command 
object type, FWDeal 1 ocateFWCommandObject has the necessary information to 
properly deallocate the given command object no matter what object type it has. 


6.3.3 FWGetFWCommandObjectType 

FWGetFWCommandObjectType returns the service class type of the given command 
object. 


OSStatus FWGetFWCommandObjectType ( 

FWCommandObjectID fwCommandObjectID, 

UInt32 *pFWCommandObjectType); 


--> fwCommandObjectID Command object to get type of. 

<-- pFWCommandObjectType Returned service class type of command 

object. 


DESCRIPTION 

FWGetFWCommandObjectType returns the service class type of the given command 
object. There is no set version of this routine, since the command object type is 
set by the command object allocation routine for its service class. Because each 
service class requires different sets of allocations for command objects, drivers 
cannot set or change the object types of command objects. 


6.3.4 FWGetFWCommandType 

FWGetFWCommandType returns the type of service command that the given 
command object has been set up for. 


OSStatus FWGetFWCommandType ( 

FwCommandObjectID fwCommandObjectID, 

UInt32 *pFWCommandType); 
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--> fwCommandObjectlD Command object to get command type of. 

<-- pFWCommandType Returned service command type of 

command object. 


DESCRIPTION 

FWGetFWCommandType returns the type of service command that the given 
command object has been set up for. The type specifies the command in the 
command object's service class for which the command object is used. The 
command type may be kFWRead, kFWWri te, kFWIni ti al i zelsochronousChannel, or 
any of the other types of service commands that may be issued. 

Because the command type is set by the particular service routine called, there 
is no set routine for the command type. 


6.3.5 FWSetFWCommandFWReferencelD 

FWSetFWCommandFWReferencelD sets the FWReferencelD that is to be the target of a 
FireWire service. 

OSStatus FWSetFWCommandFWReferencelD ( 

FWCommandObj ectlD fwCommandObj ectlD, 

FWReferencelD fwReferencelD); 

--> fwCommandObjectlD Command object to set FWReferencelD of. 

--> fwReferencelD Reference to target of FireWire service. 


DESCRIPTION 

FWSetFWCommandFWReferencelD sets the FWReferencelD that is to be the target of a 
FireWire service. For most services, this may be any of the different types of 
reference IDs. There is no meaningful default reference ID, so this parameter 
must be explicitly set for all FireWire service commands. 


6.3.6 FWGetFWCommandFWReferencelD 

FWGetFWCommandFWReferencelD returns the FWReferencelD that is to be the target 
of a FireWire service. 
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OSStatus WGetFWCommandFWReferencelD ( 

FWCommandObjectID fwCommandObjectlD, 

FWReferencelD *pFWReferenceID); 


--> fwCommandObjectlD Command object to get FWReferencelD of. 

<-- pFWReferencelD Reference to target of FireWire service. 


DESCRIPTION 

FWGetFWCommandFWReferencelD returns the FWReferencelD that is to be the target 
of a FireWire service. 


6.3.7 FWSetFWCommandFlags 

FWSetFWCommandFl ags sets flags that may modify the behavior of a FireWire 
service command. 


OSStatus FWSetFWCommandFlags ( 

FWCommandObjectID fwCommandObjectlD, 

UInt32 commandFlags); 


--> fwCommandObjectlD Command object to set command flags of. 

--> commandFlags Flags that modify a service command's 

behavior. 


DESCRIPTION 

FWSetFWCommandFl ags sets flags that may modify the behavior of a FireWire 
service command. 

If the kFWCommandSyncFl ag is set, any FireWire service routine called with the 
command object will not return until the service command is complete. If this 
flag is not set, a FireWire service routine may return before the service 
command has been completed. In this case, a driver will usually specify a 
completion routine that will be called when the service command has 
completed. The only time that a FireWire service routine may be called with the 
kFWCommandSyncFl ag flag set is at task level. 

The commandFl ags value defaults to 0. 
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6.3.8 FWGetFWCommandFlags 

FWGetFWCommandFl ags returns the flags that have been set to modify the behavior 
of a FireWire service command. 


OSStatus FWGetFWCommandFl 

FWCommandObj ectlD 
UIn 132 


ags ( 

fwCommandObj ectlD, 
*pCommandFlags); 


--> fwCommandObj ectl D Command object to get command flags of. 

<-- pCommandFl ags Returned flags set to modify a service 

command's behavior. 


DESCRIPTION 

FWGetFWCommandFl ags returns the flags that have been set to modify the behavior 
of a FireWire service command. 


6.3.9 FWGetFWCommandStatus 

FWGetFWCommandStatus returns the final status of a FireWire service command. 


OSStatus FWGetFWCommandStatus ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 *pCommandStatus); 


--> fwCommandObj ectl D Command object to get status of. 

<-- pCommandStatus Returned status of FireWire service 

command. 


DESCRIPTION 

FWGetFWCommandStatus returns the final status of a FireWire service command. 
The returned status may be any value returned from any routine call. If the 
command completed successfully, the returned status will be n o E r r. If the 
command did not complete successfully, the returned status will indicate the 
error that occurred (e.g., timeout Err, invalidIDErr, etc.). This call will not return 
any meaningful result until the FireWire service command has completed. 
Because setting the status outside of a FireWire service command is not 
meaningful, there is no set routine provided. 
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6.3.10 FWSetFWCommandCompletionProc 

FWSetFWCommandCompl eti onProc sets the procedure to call upon completion of a 
FireWire service command. 

OSStatus FWSetFWCommandCompletionProc ( 

FWCommandObjectID fwCommandObjectID, 

FWCommandCompletionProcPtr completionProc); 

--> fwCommandObjectID Command object to set completion proc of. 

--> compl etionProc Procedure to call upon completion of the 

FireWire service command. 


DESCRIPTION 

FWSetFWCommandCompl eti onProc sets the procedure to call when a FireWire 
service command completes. This procedure will be called whether or not the 
command completed successfully. The procedure will be passed the 
fwCommandObjectID given to the FireWire service command, the final status of 
the command, and the completion procedure data set for the fwCommandObj ectl D. 

The completion procedure may make any calls callable at secondary interrupt 
level. The completion procedure may also make any FireWire service calls that 
are not specified as being only callable at task time. Thus, the completion 
procedure may make further service calls but may only make them 
asynchronously. The fwCommandObjectID used for the FireWire service command 
will be free to be used again by the completion procedure. 

The default value of the completion procedure is nit, 


6.3.11 FWGetFWCommandCompletionProc 

FWGetFWCommandCompl eti onProc returns the procedure that will be called upon 
completion of a FireWire service command. 

OSStatus FWGetFWCommandCompletionProc ( 

FwCommandObjectID fwCommandObjectID, 

FWCommandCompletionProcPtr* pCompletionProc); 

--> fwCommandObjectID Command object to get completion proc of. 

<-- pCompl eti onProc Procedure that will be called on completion 

of the FireWire service command. 
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DESCRIPTION 

FWGetFWCommandCompl eti onProc returns the procedure that will be called upon 
completion of a FireWire service command. 


6.3.12 FWSetFWCommandCompletionProcData 

FWSetFWCommandCompl eti onProcData sets a 32-bit value for use by the procedure 
that will be called upon completion of a Firewire service command. 


OSStatus FWSetFWCommandCompletionProcData ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 completionProcData ); 


--> fwCommandObj ectl D Command object to set completion proc 

data of. 

--> compl eti onProcData 32-bit data for use by the procedure that 

will be called upon completion of the 
FireWire service command. 


DESCRIPTION 

FWSetFWCommandCompl eti onProcData sets a 32-bit value that is passed to the 
FireWire service completion procedure. This value provides a context for the 
completion procedure and may be set to any value. Typically a driver will set 
this value to a pointer to a private data structure that holds the driver's context. 


6.3.13 FWGetFWCommandCompletionProcData 

FWGetFWCommandCompl eti onProcData returns the 32-bit value used by the 
procedure that will be called upon completion of a Firewire service command. 


OSStatus FWGetFWCommandCompletionProcData ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 *pCompletionProcData); 
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--> 

fwCommandObjectID 

Command object to get completion 
proc data of. 

<-- 

pCompletionProcDataReturned 

32-bit data used by the procedure 
that will be called upon 
completion of the FireWire 
service command. 


DESCRIPTION 

FWGetFWCommandCompl eti onProcData returns the 32-bit value that will be passed 
in to the FireWire service completion procedure. 


6.3.14 FWSetFWCommandParams 

FWSetFWCommandParams sets all of the parameters that are used for the basic 
FireWire service commands. 

OSStatus FWSetFWCommandParams ( 



FWCommandObjectID 

fwCommandObjectID, 


FWReferencelD 

fwReferencelD, 


UInt32 

commandFlags, 


FWCommandCompletionProcPtr 

completionProc, 


UInt32 

completionProcData); 

--> 

fwCommandObjectID 

Command object to set params of. 

--> 

fwReferencelD 

Reference to target of FireWire service. 

--> 

commandFlags 

Flags that modify a service command's 
behavior. 

--> 

completionProc 

Procedure to call upon completion of 
the FireWire service command. 

--> 

completionProcData 

32-bit data for use by the procedure 


that will be called upon completion 
of the FireWire service command. 


DESCRIPTION 

FWSetFWCommandParams sets all of the parameters that are used for the basic 
FireWire service commands. This routine is provided for convenience to allow 
a driver to set all of the parameters with one procedure call. 
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6.3.15 FWGetFWCommandParams 

FWGetFWCommandPa rams returns all of the parameters that are used for the basic 
FireWire service commands. 

OSStatus FWSetFWCommandParams ( 



FWCommandObj ectlD 

fwCommandObj ectl D, 


UInt32 

*pFWCommandObj ectType, 


UInt32 

*pFWCommandType, 


FWReferencelD 

*pFWReferencel D, 


UInt32 

*pCommandFlags, 


UInt32 

*pCommandStatus, 


FWCommandCompletionProcPtr 

*pCompletionProc, 


UInt32 

*pCompletionProcData ); 

--> 

fwCommandObj ectlD 

Command object to get params of. 

<-- 

pFWCommandObj ectType 

Returned service class type of 
command object. 

<-- 

pFWCommandType 

Returned service command type of 
command object. 

<-- 

pFWReferencelD 

Returned reference to target of 
FireWire service. 

<-- 

pCommandFlags 

Returned flags set to modify a 
service command's behavior. 

<-- 

pCommandStatus 

Returned status of FireWire service 
command. 

<-- 

pCompletionProc 

Procedure that will be called upon 
completion of the FireWire 
service command. 

<-- 

pCompletionProcData 

Returned 32-bit data used by the 


procedure that will be called upon 
completion of the FireWire service 
command. 


DESCRIPTION 

FWGetFWCommandPa rams returns all of the parameters that are used for the basic 
FireWire service commands. This routine is provided for convenience to allow 
a driver to get all of the parameters with one procedure call. In order to 
optimize this routine, FWGetFWCommandParams assumes that all of the parameter 
pointers are valid and not nil. 
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This chapter describes the services and programming interface that the Mac OS 
provides for asynchronous transactions over a FireWire bus. 


7.1 Structures, Data Types, and Constants 


7.1.1 FWAddress 


addressHi, 
address Lo; 

FWAddress, 

*FWAddressPtr; 

addressHi , addressLo 64-bit FireWire address. 

7.1.2 Asynchronous Types 

typedef Kernel ID FWAddressSpacelD; 

FWAddressSpacelD Reference to a FireWire address 

space. 


struct FWAddressStruct 
{ 

UInt32 

}; 

typedef struct FWAddressStruct 
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7.1.3 Asynchronous Constants 

The following constants specify the various possible flags for a FireWire 
address space: 

enum 


kFWAddressWriteEnable 
kFWAddressWriteRequestNotify 
kFWAddressWriteCompleteNotify 
kFWAddress Read Enable 
kFWAddressReadRequestNotify 
kFWAddressReadCompleteNotify 
kFWAddressLockEnable 
kFWAddressLockRequestNotify 
kFWAddressLockCompleteNotify 

); 

kFWAddressWriteEnable 

kFWAddressWriteRequestNotify 

kFWAddressWriteCompleteNotify 

kFWAddress Read Enabl e 

kFWAddressReadRequestNotify 

kFWAddressReadCompleteNotify 

kFWAddressLockEnable 

kFWAddressLockRequestNotify 

kFWAddressLockCompleteNotify 


enum 
f 

kFWAsynchOverrideMaxPayload 
kFWAsynchDisableAddress Increment 
kFWAsynchAbsoluteAddress 
kFWAsynchFailOnBusReset 

) ; 


(1 

« 

0) 

(1 

« 

1) 

(1 

« 

2) 

(1 

« 

3) 

(1 

« 

4) 

(1 

« 

5) 

(1 

« 

6) 

(1 

« 

7) 

(1 

« 

8) 


Enable writes to the address space. 

Notify driver on write requests 
to the address space. 

Notify driver on completed 
writes to the address space. 

Enable reads to the address space. 

Notify driver on read requests 
to the address space. 

Notify driver on completed reads 
to the address space. 

Enable locks to the address space. 

Notify driver on lock requests 
to the address space. 

Notify driver on completed locks 
to the address space. 


(1 

« 

0) 

(1 

« 

1) 

(1 

« 

2) 

(1 

<< 

3) 
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kFWAsynchOverri deMaxPayl oad Specifies that the 

maxPayloadSize of an 
asynchronous packet transaction 
service command object should be 
used intead of the maxPayl oadSi ze 
set for the target device. 

kFWAsynchDi sabl eAddress I ncrement Specifies that automatic address 

incrementing should not be 
performed when an asynchronous 
transfer is split into 
multiple packets. 

kFWAsynchAbsol uteAddress Specifies that the full 64 bits 

of the addressHi /addressLo 

parameters should be used. 

kFWAsynchFai 1 OnBusReset Specifies that an asynchronous 

transfer should fail and stop if 
a bus reset occurs. 


7.2 Asynchronous Transaction Routines 
7.2.1 FWRead 

FWRead sends a read request to the FireWire bus. 

OSStatus FWRead ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWRead attempts to read 1 ength bytes of data from the given address. If it fails, 
FWRead retries the request numRetri es times and returns retry ExceededErr if the 
request was not successful after the given number of retries. 

Depending upon the parameters, FWRead interprets the address fields as either 
an absolute 64-bit address or a 48-bit address offset. If the given fwReferencelD 
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references a specific device such as FWDri verlD or FWDevicelD, the address is 
interpreted as an offset and is added to the base address of the device 
associated with the fwReferencel D. If the given fwReferencelD does not 
reference a specific device such as FWIMID, the address is interpreted as an 
absolute 64-bit address. 

If the given address is interpreted as an offset, the calling code does not need to 
know the node ID or bus ID of the device it wants to read from. FWRead will 
determine the nodelD and busID from the given fwReferencelD. In addition, 
FWRead will retry the transaction if a bus reset occurs. Thus, the calling code 
does not need to worry about bus resets affecting the read operation, nor does 
the calling code need to specify a generation value. If, however, the given 
address is interpreted as an absolute address, the calling code must specify a 
generation value so FWRead can determine if the given address is up to date 
with the most recent topology map. In this case, if a bus reset occurs, the 
command fails and commandStatus is set to busReconf iguredErr. 

If the fwReferencelD does not reference a specific device such as FWIMID, the 
calling code must specify the maximum packet payload size in maxPayl oadSi ze. 
This value specifies the maximum payload size the target device can accept in a 
packet. If this size is less than the requested length, FWRead splits the transfer 
into multiple read packets whose payloads are no greater than maxPayl oadSi ze. 
If the fwReferencelD references a specific device such as FWDri verlD or 
FWDevi cel D, FWRead uses the maximum payload size set for the device with 
FWSetMaxPayl oadSi ze. 


7.2.2 FWWrite 

FWWri te sends a write request onto the FireWire bus. 

OSStatus FWWrite ( 

FWCommandObjectID fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWWri te attempts to write 1 ength bytes of data to the given address. It retries 
the request numRetri es times and returns retry ExceededErr if the request was 
not successful after the given number of retries. 
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Depending upon the parameters, FWWri te interprets the address fields as either 
an absolute 64-bit address or a 48-bit address offset. If the given fwReferencelD 
references a specific device such as FWDriverlDor FWDevicelD, the address is 
interpreted as an offset and is added to the base address of the device 
associated with the fwReferencelD. If the given fwReferencelD does not 
reference a specific device such as FWIMID, the address is interpreted as an 
absolute 64-bit address. 

If the given address is interpreted as an offset, the calling code does not need to 
know the node ID or bus ID of the device it wishes to write to. FWWri te will 
determine the nodelD and busID from the given fwReferencelD. In addition, 

FWWri te will retry the transaction if a bus reset occurs. Thus, the calling code 
does not need to worry about bus resets affecting the write operation, nor does 
the calling code need to specify a generation value. If, however, the given 
address is interpreted as an absolute address, the calling code must specify a 
generation value so FWWri te can determine if the given address is up to date 
with the most recent topology map. In this case, if a bus reset occurs, the 
command fails and commandStatus is set to busReconf i guredErr. 

If the fwReferencelD is a FWIMID, the calling code must specify the maximum 
packet payload size in maxPayl oadSi ze. This value specifies the maximum 
payload size the target device can accept in a packet. If this size is less than the 
requested length, FWWri te splits the transfer into multiple write packets whose 
payloads are no greater than maxPayl oadSi ze. If the fwReferencelD is an 
FWDri verlD, FWWri te uses the maximum payload size set for the device with 
FWSetMaxPayloadSize. 


7.2.3 FWCompareAndSwap 

FWCompareAndSwap performs an atomic compare and swap operation upon a 
given address, using the FireWire compare and swap lock transaction. 

OSStatus FWBitCompareAndSwap ( 

FwCommandObjectlD fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWCompareAndSwap attempts to perform an atomic compare and swap operation 
on the destination address, using the FireWire compare and swap lock 
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transaction. The first half of the command object buffer is the argument value 
of the compare and swap. The second half of the command object buffer is the 
data value of the compare and swap. If the value at the destination address is 
equal to the argument value, the destination address will be set to the data 
value; otherwise, the destination address will remain unchanged. The length 
specified in the command object should be either 8 or 16 bytes. 

If FWCompareAndSwap completes with a status of noErr, the compare swap 
transaction returns in the command object buffer the value of the destination 
address before the compare swap. If it's identical to the argument value, the 
compare and swap took affect and the destination address will have been set to 
the data value of the compare and swap transaction. Otherwise, the comand 
and swap did not take affect and the destination address will remain set to the 
value returned in the command object buffer. 

Depending upon the parameters, FWBi tCompareAndSwap interprets the address 
fields as either an absolute 64-bit address or a 48-bit address offset. If the given 
fwReferencel D references a specific device such as FWDri ver ID or FWDevi cel D, the 
address is interpreted as an offset and is added to the base address of the 
device associated with the fwReferencelD. If the given fwReferencelD does not 
reference a specific device such as FWIMID, the address is interpreted as an 
absolute 64-bit address. 

If the given address is interpreted as an offset, the calling code does not need to 
know the nodelDorbusIDof the device it wishes to write to. FWCompa re And Swap 
will determine the nodelD and busID from the given fwReferencelD. In addition, 
FWCompa reAndSwap will retry the transaction if a bus reset occurs. Thus, the 
calling code does not need to worry about bus resets affecting the operation, 
nor does the calling code need to specify a generation value. If, however, the 
given address is interpreted as an absolute address, the calling code must 
specify a generation value so FWCompareAndSwap can determine if the given 
address is up to date with the most recent topology map. In this case, if a bus 
reset occurs, the command fails and commandStatus is set to busReconf i guredErr. 


7.2.4 FWBitAnd 

FWBi tAnd performs an atomic bitwise AND operation upon a given address, 
using the FireWire compare and swap lock transaction. 
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OSStatus FWBitAnd ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWBitAnd attempts to perform an atomic bitwise AND operation on the 
destination address, using the FireWire compare and swap lock transaction. It 
first reads the data from the address, computes the new value, and attempts a 
compare swap. The compare swap transaction returns the value of the 
destination address before the compare swap. If it's identical to the value that 
was initially read, the compare swap should have written the newly computed 
value and the bitwise AND operation is successful. Otherwise, the bitwise 
AND must be restarted. FWBi tAnd retries the request numRetri es times and 
returns retryExceededErrif the request is not successful after the given number 
of retries. 

FWBitAnd returns the old value before the operation in buffer. The length of the 
transaction must be either 4 or 8 bytes. 

Depending upon the parameters, FWBi tAnd interprets the address fields as 
either an absolute 64-bit address or a 48-bit address offset. If the given 
fwReferencelD references a specific device such as FWDri verlD or FWDevicelD, the 
address is interpreted as an offset and is added to the base address of the 
device associated with the fwReferencelD. If the given fwReferencelD does not 
reference a specific device such as FWIMID, the address is interpreted as an 
absolute 64-bit address. 

If the given address is interpreted as an offset, the calling code does not need to 
know the node ID or bus ID of the device it wishes to write to. FWBitAnd will 
determine the nodelD and busID from the given fwReferencelD. In addition, 

FWBi tAnd will retry the transaction if a bus reset occurs. Thus, the calling code 
does not need to worry about bus resets affecting the operation, nor does the 
calling code need to specify a generation value. If, however, the given address 
is interpreted as an absolute address, the calling code must specify a generation 
value so FWBi tAnd can determine if the given address is up to date with the 
most recent topology map. In this case, if a bus reset occurs, the command fails 
and commandStatus is set to busReconfiguredErr. 
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7.2.5 FWBitOr 

FWBi tOr performs an atomic bitwise OR operation upon a given address, using 
the FireWire compare and swap lock transaction. 

OSStatus FWBitOr ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWBi tOr is identical to FWBi tAnd (Section 7.2.4) except that it performs an atomic 
bitwise OR operation upon the destination address. 


7.2.6 FWBitXor 

FWBi tXor performs an atomic bitwise exclusive OR operation upon the given 
address, using the FireWire compare and swap lock transaction. 

OSStatus FWBitXor ( 

FwCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWBi tXor is identical to FWBi tAnd (Section 7.2.4) except that it performs an 
atomic bitwise exclusive-OR upon the destination address. 


7.2.7 FWIncrement 

FWIncrement performs an atomic increment operation upon a given address, 
using the FireWire compare and swap lock transaction. 

OSStatus FWBitlncrement ( 

FwCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 
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DESCRIPTION 

FWBIncrement is identical to FWBi tAnd (Section 7.2.4) except that it performs an 
atomic increment upon the destination address. In addition, FWBIncrement does 
not take any input in buffer. 


7.2.8 FWDecrement 

FWDecrement performs an atomic decrement operation upon the given address, 
using the FireWire compare and swap lock transaction. 

OSStatus FWBitDecrement ( 

FWCommandObjectlD fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWDecrement is identical to FWIncrement (Section 7.2.7) except that it performs an 
atomic decrement upon the destination address. 


7.2.9 FWAdd 

FWAdd performs an atomic add operation upon a given address, using the 
FireWire compare and swap lock transaction. 

OSStatus FWAdd ( 

FwCommandObjectlD fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWAdd is identical to FWBi tAnd (Section 7.2.4) except that it performs an atomic 
add upon the destination address. 


7.2.10 FWThresholdAdd 

FWThreshol dAdd performs an atomic threshold add operation upon a given 
address, using the FireWire compare and swap lock transaction. 
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OSStatus FWThresholdAdd ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWThreshol dAdd is identical to FWBi tAnd (Section 7.2.4) except that it performs an 
atomic threshold add upon the destination address. The buffer contains both 
the value to add to the destination and a threshold argument. If the result of 
the addition is greater than the threshold argument, the addition is not 
performed. The first value in the buffer is the threshold argument value, and 
the second value in the buffer is the value to add to the destination. These may 
be either 4 or 8 bytes in size. Thus, length must be either 8 or 16. 


7.2.11 FWThresholdSubtract 

FWThreshol dSubtract performs an atomic threshold subtract operation upon a 
given address, using the FireWire compare and swap lock transaction. 

OSStatus FWThresholdSubtract ( 

FwCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWThreshol dSubtract is identical to FWThreshol dAdd (Section 7.2.10) except that it 
performs an atomic threshold subtract upon the destination address. The buffer 
contains both the value to subtract from the destination and a threshold 
argument. If the result of the subtraction is less than the threshold argument, 
the subtraction is not performed. The first value in the buffer is the threshold 
argument, and the second value in the buffer is the value to subtract from the 
destination. These may be either 4 or 8 bytes in size. Thus, length must be 
either 8 or 16. 
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7.2.12 FWClippedAdd 

FWCl i ppedAdd performs an atomic clipped add operation upon a given address, 
using the FireWire compare and swap lock transaction. 

OSStatus FWClippedAdd ( 

FWCommandObjectID fwCommandObjectID); 

- -> fwCommandOb ject ID Command object controlling this service. 


DESCRIPTION 

FWCl i ppedAdd is identical to FWBi tAnd (Section 7.2.4) except that it performs an 
atomic clipped add upon the destination address. The buffer contains both the 
value to add to the destination and a clip argument. If the result of the addition 
is greater than the clip argument, the destination address will be set to the clip 
value; otherwise, the destination address will be set to the result of the 
addition. The first value in the buffer is the clip argument value to clip the 
addition, and the second value in the buffer is the value to add to the 
destination. These may be either 4 or 8 bytes in size. Thus, length must be 
either 8 or 16. 


7.2.13 FWClippedSubtract 

FWClippedSubtract performs an atomic clipped subtract operation upon a given 
address, using the FireWire compare and swap lock transaction. 

OSStatus FWClippedSubtract ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWCl i ppedSubtract is identical to FWCl i ppedAdd (Section 7.2.12) except that it 
performs an atomic clipped subtract upon the destination address. The buffer 
contains both the value to subtract from to the destination and a clip argument. 
If the result of the subtraction is less than the clip argument, the destination 
address will be set to the clip value; otherwise, the destination address will be 
set to the result of the subtraction. The first value in the buffer is the clip 
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argument value to clip the subtraction, and the second value in the buffer is the 
value to subtract from the destination. These may be either 4 or 8 bytes in size. 
Thus, 1 ength must be either 8 or 16. 


7.2.14 FWAIIocateAsynchCommandObject 

FWAl 1 ocateAsynchCommandObject creates a command object that may be used 
with the asynchronous packet transaction commands. 

OSStatus FWAIIocateAsynchCommandObject ( 

FWCommandObjectID *pFWCommandObjectID); 

< - - pFWCommandObj ectl D Returned reference to created FireWire 

asynchronous packet transaction service 
command object. 


DESCRIPTION 

FWAl 1 ocateAsynchCommandObject creates a FireWire service command object for 
the asynchronous packet transaction class of FireWire services. In addition to 
the basic set of command object parameters, the command object created by 
FWAl 1 ocateAsynchCommandObject will contain additional parameters specific to 
performing asynchronous packet transactions. 

The basic set of parameters will default to the same values as in 

FWAl 1 ocateFWCommandObject. Most of the asynch specific parameters have no 

meaningful default values and must be explicitly set. When fwReferencelD 

references some specific device (i.e., not just a particular FWIM), 

maxPayl oadSi ze will default to the maxPayl oadSi ze value set for the device. The 

maxRetri es parameter will default to 0, meaning that no retries will be 

attempted. The transferFl ags parameter will default to 0. 

The command object created by FWAl 1 ocateAsynchCommandObject may be 
deallocated by FWDeal 1 ocateFWCommandObject. 


7.2.15 FWSetAsynchCommandGeneration 

FWSetAsynchCommandGenerati on sets the generation value used to validate the 
node ID within the asynchronous command target address. 
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OSStatus FWSetAsynchCommandGeneration ( 

FWCommandObjectID fwCommandObjectlD, 

UInt32 generation ); 


--> fwCommandObjectlD Command object to set generation of. 

--> generation Generation value of node ID. 


DESCRIPTION 

FWSetAsynchCommandGenerati on specifies the generation value used to validate 
the node ID within the asynch command target address. The generation value 
will only be used when the asynch command target address is a full 64-bit 
address and not a 48-bit address offset. Typically, if the fwReferencelD set for 
the command object references a specific device, the asynch command target 
address will be a 48-bit address offset, and the generation value will not be 
needed. 


7.2.16 FWGetAsynchCommandGeneration 

FWGetAsynchCommandGenerati on returns the generation value used to validate the 
node ID within the asynch command target address. 


OSStatus FWGetAsynchCommandGeneration ( 

FWCommandObjectID fwCommandObjectlD, 

UIn t3 2 *pGeneration); 


--> fwCommandObjectlD 
<-- pGeneration 


Command object to get generation of. 
Returned generation value of node ID. 


DESCRIPTION 

FWGetAsynchCommandGenerati on returns the generation value used to validate the 
node ID within the asynch command target address. 


7.2.17 FWSetAsynchCommandAddress 

FWSetAsynchCommandAddress sets the target address of an asynchronous 
transaction command. 
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OSStatus 


FWSetAsynchCommandAddress ( 


FWCommandObj ectlD 

UInt32 

UInt32 


fwCommandObj ectlD, 
addressHi, 
addressLo); 


--> fwCommandObjectID Command object to set address of. 

--> addressHi, addressLo 64-bit address or 48-bit address offset target 

of asynchronous transaction. 


DESCRIPTION 

FWSetAsynchCommandAddress specifies the target address of an asynchronous 
transaction command. The target address will either be a full 64-bit address or 
a 48-bit address offset depending upon the other parameters specified for the 
asynch command. Typically, if the fwReferencelD set for the command object 
references a specific device, the asynch command target address will be a 48-bit 
address offset. 


7.2.18 FWGetAsynchCommandAddress 

FWGetAsynchCommandAddress returns the target address of an asynchronous 
transaction command. 


OSStatus 


FWGetAsynchCommandAddress ( 


FWCommandObj ectlD 
UInt32 
UI n 132 


fwCommandObj ectl D, 
*pAddressHi, 
*pAddressLo); 


--> fwCommandObj ect ID Command object to get address of. 

<-- addressHi , addressLo Returned target address of 

asynchronous transaction. 


DESCRIPTION 

FWGetAsynchCommandAddress returns the target address of an asynchronous 
transaction command. 
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7.2.19 FWSetAsynchCommandBuffer 

FWSetAsynchCommandBuf fer sets the buffer for sending and/or receiving data for 
an asynchronous transaction command. 


OSStatus FWSetAsynchCommandBuffer ( 

FWCommandObjectID fwCommandObjectID, 

Ptr buffer); 


-> fwCommandObjectID 
-> buffer 


Command object to set buffer of. 

Buffer for sending and or receiving data. 


DESCRIPTION 

FWSetAsynchCommandBuffer specifies the buffer for sending and/or receiving 
data for an asynchronous transaction command. For FWWri te commands, this 
buffer will contain the data to be written to a remote device. For FWRead 
commands, this buffer will contain the data read from a remote device when 
the command completes. For the various asynchronous lock transaction 
commands, this buffer will contain the data and argument to send to a remote 
device; upon completion of the command, this buffer will contain the data at 
the target address before the lock transaction. 


7.2.20 FWGetAsynchCommandBuffer 

FWGetAsynchCommandBuf fer returns the buffer for sending and/or receiving data 
for an asynchronous transaction command 


OSStatus 


FWGetAsynchCommandBuffer ( 


FWCommandObjectID 

Ptr 


fwCommandObjectID, 
*pBuffer); 


--> fwCommandObjectID 
<-- pBuffer 


Command object to get buffer of 
Returned buffer for sending 
and/or receiving data. 


DESCRIPTION 

FWGetAsynchCommandBuffer returns the buffer for sending and/or receiving data 
for an asynchronous transaction command. 
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7.2.21 FWSetAsynchCommandLength 

FWSetAsynchCommandLength sets the length of data to be sent or received for an 
asynchronous transaction command. 


OSStatus FWSetAsynchCommandLength ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 1ength ); 


--> fwCommandObjectlD 
--> length 


Command object to set length of. 
Length of data to send or receive. 


DESCRIPTION 

FWSetAsynchCommandLength specifies the length of data to be sent or received for 
an asynchronous transaction command. The buffer specified by 
FWSetAsynchCommandBuffer should be at least as large as the length specified by 

FWSetAsynchCommandLength. 


7.2.22 FWGetAsynchCommandLength 

FWGetAsynchCommandLength returns the length of data to be sent or received for 
an asynchronous transaction command 


OSStatus FWGetAsynchCommandLength ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 *pLength); 


--> fwCommandObjectlD 
<-- pLength 


Command object to get length of. 

Returned length of data to send or receive. 


DESCRIPTION 

FWGetAsynchCommandLength returns the length of data to be sent or received for 
an asynchronous transaction command. 


7.2.23 FWGetAsynchCommandBytesTransferred 

FWGetAsynchCommandBytesTransferred returns the actual amount of data 
transferred by and asynchronous transaction command. 
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OSStatus FWGetAsynchCommandBytesTransferred ( 

FwCommandObjectlD fwCommandObjectlD, 

UInt32 *pBytesTransferred); 


--> fwCommandObjectlD Command object to get bytesTransferred of. 

<-- pBytesTransferred Returned amount of data actually 

transferred by an asynchronous 
transaction command. 


DESCRIPTION 

FWGetAsynchCommandBytesTransferred returns the actual amount of data 
transferred by an asynchronous transaction command. Typically, 
pBytesTransferred will be equal to the length specified by 
FWSetAsynchCommandLength; this will always be the case when a FireWire 
asynchronous packet transaction service completes with a status of noErr. If the 
requested transaction was broken into multiple packets, and an error occurred 
after some of the packets were transmitted or received, 

FWGetAsynchCommandBytesT ransferred will return the amount of data that was 
successfully transmitted or received before the error occurred. 


7.2.24 FWSetAsynchCommandMaxPayloadSize 

FWSetAsynchCommandMaxPayl oadSi ze sets the maximum payload size for an 
asynchronous transaction command. 


OSStatus FWSetAsynchCommandMaxPayloadSize ( 

FwCommandObjectlD fwCommandObjectlD, 

UInt32 maxPayloadSize); 


--> fwCommandObjectlD Command object to set maxPayl oadSi ze of. 

--> maxPayl oadSi ze Maximum payload size for an asynchronous 

transaction command. 


DESCRIPTION 

FWSetAsynchCommandMaxPayl oadSi ze specifies the maximum payload size for an 
asynchronous transaction command. If the fwReferencelD set for the command 
object references a specific device, maxPayl oadSi ze will default to the maximum 
payload size set for the device by FWSetMaxPayl oadSi ze. The device's default 
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maximum payload size may be overridden by setting the 

kFWAsynchOverri deMaxPayload flag in transferFlags. 

The maximum payload size will determine the maximum payload size for all 
asynchronous packet transactions used to complete the FireWire asynchronous 
packet transaction service using the command object. If the length parameter 
for the command object is larger than the maximum packet size, the operation 
will be broken up into multiple transactions with payloads no greater than the 
maximum payload size. 

The maximum payload size for the lock transactions is ignored. It is assumed 
that the driver issuing the lock request knows that the target node can support 
the lock transaction size. 


7.2.25 FWGetAsynchCommandMaxPayloadSize 

FWGetAsynchCommandMaxPayl oadSi ze returns the maximum payload size for an 
asynchronous transaction command. 


OSStatus FWGetAsynchCommandMaxPayloadSize ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 *pMaxPayloadSize); 


--> fwCommandObj ectl D Command object to get maxPayloadSize of. 

< - - pMaxPay 1 oadSi ze Returned maximum payload size for an 

asynchronous transaction command. 


DESCRIPTION 

FWGetAsynchCommandMaxPayl oadSi ze returns the maximum payload size for an 
asynchronous transaction command. 


7.2.26 FWSetAsynchCommandMaxRetries 

FWSetAsynchCommandMaxRetri es sets the maximum number of times an 
asynchronous transaction will be retried. 

OSStatus FWSetAsynchCommandMaxRetries ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 maxRetries); 
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--> fwCommandObjectID Command object to set maxRetri es of. 

--> maxRetri es Maximum number of times to retry an 

asynchronous transaction. 


DESCRIPTION 

FWSetAsynchCommandMaxRetri es specifies the maximum number of times an 
asynchronous transaction will be retried. When a driver uses one of the 
FireWire asynchronous packet transaction services, the services will attempt to 
complete the specified transactions. If a transaction fails (e.g., times out), the 
services will retry the transaction up to the maximum number of times 
specified by maxRetri es. If the transaction has not been successfully completed 
after the maximum number of retries, the FireWire asynchronous packet 
transaction service will complete with an error status. 

The maxRetri es parameter defaults to 0, indicating that the FireWire 
asynchronous packet transaction services should make only one attempt to 
complete a transaction. 


7.2.27 FWGetAsynchCommandMaxRetries 

FWGetAsynchCommandMaxRetri es returns the maximum number of times an 
asynchronous transaction will be retried. 


OSStatus 


FWGetAsynchCommandMaxRetries ( 


FWCommandObjectID 
UI n 13 2 


fwCommandObjectID, 
*pMaxRetries); 


--> fwCommandObjectID 
<-- pMaxRetries 


Command object to get maxRetri es of. 
Returned maximum number of times to 
retry an asynchronous transaction. 


DESCRIPTION 

FWGetAsynchCommandMaxRetri es returns the maximum number of times an 
asynchronous transaction will be retried. 
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7.2.28 FWSetAsynchCommandTransferFlags 

FWSetAsynchCommandTransferFl ags sets the flags to control the transfer of 
asynchronous packets. 


OSStatus FWSetAsynchCommandTransferFlags ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 transferFlags); 


--> fwCommandObj ectl D Command object to set transferFlags of. 

--> transferFlags Flags controlling the transfer of 

asynchronous packets. 


DESCRIPTION 

FWSetAsynchCommandT ransferFl ags specifies the flags to control the transfer of 
asynchronous packets. 

The kFWAsynchOverri deMaxPayl oad flag indicates that the maxPayl oadSi ze 

parameter specified for the command object should be used instead of the 

maxPayl oadSi ze value set for the target device by FWSetMaxPayl oadSi ze. 

The kFWAsynchDi sabl eAddress Increment flag indicates that the automatic 
address incrementing should not be performed when an asynchronous transfer 
is split into multiple packets. If the size of an asynchronous transfer exceeds 
maxPayl oadSi ze, the transfer is broken into smaller packets. If the 
kFWAsynchDi sabl eAddressIncrement flag is not set, the target address of 
successive packets will be incremented so that the packet data may be 
concatenated into the target address range. If the 

kFWAsynchDi sabl eAddressIncrement flag is not set, successive packets will be 
sent to the same base address. 

The kFWAsynchAbsol uteAddress flag specifies that the full 64 bits of the 
addressHi and addressLo parameters specified for the command object should 
be used. If the kFWAsynchAbsol uteAddress flag is not set, the FireWire services 
will attempt to calculate the higher order 16 bits of the target address using the 
fwReferencel D specified for the command object; if the upper 16 bits may be 
obtained from the fwReferencel D, only the lower 48 bits of addressHi and 
addressLo will be used. If the kFWAsynchAbsol uteAddress flag is set, the FireWire 
services will use all 64 bits of the addressHi and addressLo parameters. If the 
kFWAsynchAbsol uteAddress flag is set, the generation parameter must be set to 
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the generation of the topology map used to calculate the upper 16 bits of the 
addressHi parameter. 

The kFWAsynchFai 1 OnBusReset flag specifies that the requested asynchronous 
transfer will fail and stop if a bus reset occurs. If the kFWAsynchFai 1 OnBusReset 
flag is not set and a bus reset occurs before an asynchronous transfer is 
completed, the FireWire services will attempt to recompute the upper 16 bits of 
the target address of the transfer; if the FireWire services are successful, the 
asynchronous transfer will continue using the recomputed address. If the 
kFWAsynchFai 1 OnBusReset flag is set, the FireWire services will not attempt to 
recompute the target address and will stop the transfer. If the 
kFWAsynchFai 1 OnBusReset flag is set, the generation parameter must be set to the 
bus generation value for which the requested asynchronous transfer is valid; if 
generation is different from the current generation value, the transfer will fail 
and stop. 

The transferFl ags value defaults to 0. 


7.2.29 FWGetAsynchCommandTransferFlags 

FWGetAsynchCommandTransferFl ags returns the flags to control the transfer of 
asynchronous packets. 


OSStatus FWGetAsynchCommandTransferFlags ( 

FWCommandObjectlD fwCommandObjectlD, 

UInt32 *pTransferFlags); 


--> fwCommandObjectlD Command object to get transferFlags of. 

<-- pTransferFlags Returned flags controlling the transfer 

of asynchronous packets. 


DESCRIPTION 

FWGetAsynchCommandT ransferFl ags returns the flags to control the transfer of 
asynchronous packets. 


7.2.30 FWSetAsynchCommandParams 

FWSetAsynchCommandParams sets all of the parameters that are used for the 
FireWire asynchronous packet transaction service commands. 
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OSStatus 


FWSetAsynchCommandParams ( 


FWCommandObj ectlD 

UInt32 

UInt32 

UInt32 

Ptr 

UInt32 

UInt32 

UInt32 

UInt32 


fwCommandObj ectlD, 
generation, 
addressHi, 
addressLo, 
buffer, 

1ength, 

maxPayloadSize, 
maxRetries, 
transf erFl ags); 


--> fwCommandObjectlD 

--> generation 

--> addressHi, addressLo 

--> buffer 
--> length 
--> maxPayloadSize 

--> maxRetries 

--> transferFlags 


Command object to set parameters of. 

Generation value of node ID. 

64-bit address or 48-bit address offset 

to target of asynchronous transaction. 

Buffer for sending and or receiving data. 

Length of data to send or receive. 

Maximum payload size for an asynchronous 
transaction command. 

Maximum number of times to retry an 
asynchronous transaction. 

Flags controlling the transfer of 
asynchronous packets. 


DESCRIPTION 

FWSetAsynchCommandPa rams sets all of the parameters that are used for the 
FireWire asynchronous packet transaction service commands. This routine is 
provided for convenience to allow a driver to set all of the parameters with one 
procedure call. 


7.2.31 FWGetAsynchCommandParams 

FWGetAsynchCommandPa rams returns all of the parameters that are used for the 
FireWire asynchronous packet transaction service commands. 

OSStatus FWGetAsynchCommandParams ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 *pGeneration, 

UInt32 *pAddressHi , 


154 


7.2 Asynchronous Transaction Routines 



CHAPTER 7 


Asynchronous Services 



UI n 13 2 

*pAddress Lo, 


Ptr 

*pBuffer, 


UI n 13 2 

*pLength, 


UI n 13 2 

*pBytesTransferred, 


UI n 13 2 

*pMaxPayloadSize, 


UI n 13 2 

*pMaxRetries, 


UI n 13 2 

*pT ransferFlags); 

--> 

fwCommandObjectID 

Command object to get parameters of. 

<-- 

pGeneration 

Returned generation value of node ID. 

<-- 

addressHi, addressLo 

Returned target address of asynchronous 
transaction. 

<-- 

pBuffer 

Returned buffer for sending and or 
receiving data. 

<-- 

pLength 

Returned length of data to send or receive. 

<-- 

pBytesT ransferred 

Returned amount of data actually 
transferred by an asynchronous 
transaction command. 

< - 

pMaxPayloadSize 

Returned maximum payload size for an 
asynchronous transaction command. 

<-- 

pMaxRetries 

Returned maximum number of times to 
retry an asynchronous transaction. 

<-- 

pT ransferFlags 

Returned flags controlling the transfer 


of asynchronous packets. 


DESCRIPTION 

FWGetAsynchCommandParams returns all of the parameters that are used for the 
FireWire asynchronous packet transaction service commands. This routine is 
provided for convenience to allow a driver to get all of the parameters with on 
procedure call. In order to optimize this routine, FWGetAsynchCommandParams 
assumes that all of the parameter pointers are valid and not nil. 


7.2.32 FWSetCommonAsynchCommandParams 

FWSetCommonAsynchCommandParams sets all of the parameters usually set by 
drivers that are used for the FireWire asynchronous packet transaction service 
commands. 
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OSStatus 


FWSetCommonAsynchCommandPa rams 


FWCommandObj ectlD 

UInt32 

UInt32 

Ptr 

UInt32 


fwCommandObj ectlD 
addressHi, 
addressLo, 
buffer, 

1ength) ; 


( 


--> fwCommandObjectlD 
--> addressHi, addressLo 

--> buffer 
--> length 


Command object to set common parameters of. 
64-bit address or 48-bit address offset 

to target of asynchronous transaction. 
Buffer for sending and or receiving data. 
Length of data to send or receive. 


DESCRIPTION 

FWSetCommonAsynchCommandPa rams sets all of the parameters usually set by 
drivers that are used for the FireWire asynchronous packet transaction service 
commands. This routine is provided for convenience to let a driver set all of the 
parameters usually set for drivers with one procedure call. Typically, a driver 
will change these parameters for each asynchronous packet transaction. In this 
case, the driver may set up all of the parameters when it creates the command 
object and then only change the address, buffer, and length when setting up a 
new asynchronous transaction. Thus, FWSetCommonAsynchCommandParams 
provides a more limited set of parameter setting than does 
FWSetAsyiieh Command Pa rams. 


7.2.33 FWGetCommonAsynchCommandParams 

FWGetCommonAsynchCommandPa rams returns all of the parameters usually read by 
drivers that are used for the FireWire asynchronous packet transaction service 
commands. 

OSStatus FWGetCommonAsynchCommandParams ( 

FWCommandObj ectlD fwCommandObj ectlD, 

Ptr *pBuffer, 

UInt32 *pLength, 

UInt32 *pBytesTransferred); 
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--> fwCommandObjectlD 
<-- pBuffer 

<-- pLength 

<-- pBytesTransferred 


Command object to get parameters of. 

Returned buffer for sending and or 
receiving data 

Returned length of data to send or receive. 

Returned amount of data actually 
transferred by and asynchronous 
transaction command. 


DESCRIPTION 

FWGetCommonAsynchCommandParams returns returns all of the parameters usually 
read by drivers that are used for the FireWire asynchronous packet transaction 
service commands. Typically, when a driver needs to read the parameters of an 
asynchronous packet transaction service command object, it only needs the 
buffer, length, and actual bytes transferred. This might be the case within the 
completion procedure for the service command for an asynchronous read. In 
this scenario, the driver may want to copy the read data and will want to 
acquire the buffer with the read data and the length of the data. In order to 
optimize this routine, FWGetCommonAsynchCommandParams assumes that all of the 
parameter pointers are valid and not nil. 


7.3 Asynchronous Transaction Control Routine 


7.3.1 FWSetMaxPayloadSize 

FWSetMaxPayl oadSi ze sets the maximum payload size of an asynchronous 
transaction for a given device. 


OSStatus 


FWSetMaxPayloadSize ( 


FWReferencelD 
UI n 13 2 


fwReferencelD, 
maxPayloadSize) 


--> fwReferencelD 
--> maxPayloadSize 


Reference to device to set the maximum 
payload size for. 

Maximum payload size for the device. 


7.3 Asynchronous Transaction Control Routine 
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DESCRIPTION 

FWSetMaxPayl oadSi ze sets the maximum payload size of asynchronous 
transactions sent to the device referenced by fwReferencelD. When a call is 
made to one of the asynchronous transaction routines and a reference for the 
target device is given (that is, when a 48-bit address offset is given with the 
16-bit base obtained from the device reference), the asynchronous routine uses 
the value specified by FWSetMaxPayl oadSi ze for the asynchronous transaction; 
the transaction is split into subtransactions of size maxPayl oadSi ze or less. 

When a device is first discovered, its maximum payload size is initialized to 4; 
this ensures that asynchronous transactions will not use a payload that is too 
large for the device. Note that lock transactions assume a fixed payload size 
that may be larger than 4; if the device does not support larger payload sizes, 
these lock transactions cannot be supported by the device. 


7.4 Address Allocation Routines 


7.4.1 FWAIIocateAddressSpace 


FWA1 

1 ocateAddressSpace allocates a FireWire address range on the local host. 

OSStatus FWA11 

ocateAddressSpace ( 


FWAddressSpacelD 

*pFWAddressSpa cel D , 


FWReferencelD 

fwReferencelD, 


FWAddressPtr 

pFWAddress, 


UIn 132 

size, 


Ptr 

addressBuffer, 


UInt32 

addressFl ags, 


Ptr 

pAddressSpecifi cData); 

<-- 

pFWAddressSpacelD 

Returned reference to allocated address space. 

--> 

fwReferencelD 

FireWire reference ID of the client to 



allocate address space for. 

<-- 

pFWAddress 

Returned 48-bit base address of allocated 

--> 

--> 

si ze 

addressBuffer 

address space. 

Size of requested address space. 

Buffer to use as backing store for this 


address space. 
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--> addressFlags Flags to control address space 

- -> pAddressSpeci f i cData Pointer to address space client's private data. 


DESCRIPTION 

FWA11 ocateAddressSpace allocates a FireWire address range of requested size on 
the local adapter associated with the given fw Reference ID. An ID referencing 
the allocated address space is returned in pFWAddressSpacelD, and the 48-bit 
base address is returned in pFWAddress. 

The addressFlags specify attributes about the address space such as the 
read / write permissions and whether to notify the client when the address 
space is accessed. 

An optional backing store may be provided in addressBuf fer. If no backing 
store is provided, addressFlags should have one of the notify bits set so the 
client can take some action. 

The pAddressSpeci f i cData is used by the client however it needs to. This data 
may be used when the client is notified of access to the address space. 


7.4.2 FWDeallocateAddressSpace 

FWDeal 1 ocateAddressSpace deallocates a FireWire address range. 

OSStatus FWDeallocateAddressSpace ( 

FWAddressSpacelD fwAddressSpacelD); 

--> fwAddressSpacelD Reference to address space to deallocate. 


DESCRIPTION 

FWDeal 1 ocateAddressSpace deallocates a FireWire address range allocated by 

FWA11 ocateAddressSpace. FWDeal 1 ocateAddressSpace will not deallocate any 
backing store specified by FWA11 ocateAddressSpace. 
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This chapter describes the services and programming interface that the Mac OS 
provides for isochronous transactions over a FireWire bus. 


8.1 Structures, Data Types, and Constants 


8.1.1 Isochronous Types 


typedef Kernel ID 
typedef Kernel ID 
typedef FWReferencelD 


typedef OSStatus 
IsochChannelID 
UIn t3 2 


IsochChannel ID; 
IsochPortID; 

FWIsochResourceManagerlD; 


(FWIsochChannelForceStopNotificationProc) ( 
isochChannelID, 
stopCondition); 
typedef FWIsochChannelForceStopNotificationProc 

*FWIsochChannelForceStopNotificationProcPtr; 


IsochChannellD Reference to an isochronous channel. 

IsochPortID Reference to an isochronous port. 

FWIsochResourceManagerlD Reference to the isochronous resource 

manager. 

FWIsochChannelForceStopNotificationProc 

Type of proc that's called when an 

isochronous channel is forcefully stopped. 


8.1 Structures, Data Types, and Constants 
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8.1.2 Isochronous Constants 


enum 


klnvalidFWIsochChannelID ‘ = 0, 

klnvalidFWIsochPortID = 0, 

klnvalidFWIsochResourceManagerlD = 0 

); 

klnval idFWIsochChannel ID IfaFWIsochChannellDis equal 

to this constant, it is invalid. 

klnval idFWIsochPortID IfaFWIsochPortIDis equal to 

this constant, it is invalid. 

klnval idFWIsochResourceManagerlD IfaFWIsochResourceManagerlDis 

equal to this constant, it is invalid. 

enum 

{ 

kFWIsochChannelUnknownCondition = 0, 

kFWIsochChannelNotEnoughBandwidth = 1, 

kFWIsochChannelChannelNotAvai1able = 2 

) ; 


kFWIsochChannelUnknownCondition 


kFWIsochChannelNotEnoughBandwidth 


kFWIsochChannelChannelNotAvai1abl e 


Indicates that the isochronous 
channel was stopped for an 
unknown reason. 

Indicates that the isochronous 

channel was stopped because not 
enough bandwidth was available. 

Indicates that the isochronous 

channel was stopped because the 
channel number could not be 
reallocated. 
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8.2 Isochronous Channel Routines 


8.2.1 FWAIIocatelsochronousChannellD 

FWAl 1 ocatelsochronousChannel ID creates an isochronous channel ID that is used 
by the various isochronous channel service routines. 


OSStatus 

IsochChannel ID 
Boolean 
UInt32 
UInt32 


FWAIIocatelsochronousChannellD ( 
*pIsochChannelID, 
dolRMA11ocation , 
bandwidth, 
preferredSpeed); 


<-- plsochChannel ID 


--> dolRMA11ocation 


--> bandwidth 
--> preferredSpeed 


Returned reference to this channel for 

use in subsequent isochronous channel 
service calls. 

If true, the FireWire services will 

automatically allocate and deallocate 
isochronous resources for this channel. 

Bandwidth in bits per second required for 
this channel. 

Preferred speed for this channel. 


DESCRIPTION 

FWAl 1 ocatelsochronousChannel ID performs the initial setup for an isochronous 
channel. It returns an ID that is used as a reference to the channel for the 
isochronous channel service routines, and it is initialized with the required 
bandwidth and the preferred speed. Depending upon the maximum speed of 
the devices that are later attached to the channel, the actual speed used may be 
less than the preferred speed, but not greater. The dol RMA11 ocati on parameter 
controls whether or not the FireWire services should allocation isochronous 
resources for the channel. 


8.2 Isochronous Channel Routines 
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8.2.2 FWDeallocatelsochronousChannellD 

FWDeal 1 ocatelsochronousChannel ID deallocates an isochronous channel ID 
created by FWA11 ocatelsochronousChannel ID. 

OSStatus FWDeal1ocatelsochronousChannelID ( 

IsochChannelID isochChannelID); 

--> isochChannel ID Channel ID to deallocate. 


DESCRIPTION 

FWDeal 1 ocatelsochronousChannel ID will deallocate an isochronous channel ID 
allocated by FWA1 1 ocatelsochronousChannel ID. 

FWDeal 1 ocatelsochronousChannel ID will not release the channel. This should be 
done with a separate call to FWRel easelsochronousChannel. 


8.2.3 FWAddlsochronousChannelClient 

FWAddlsochronousChannel Cl i ent adds an interested client to the isochronous 
channel specified by isochChannel ID. This client will take part in and be 
notified of all events associated with the given isochronous channel. 


OSStatus 


FWAddlsochronousChannelClient ( 


IsochChannelID 
FWReferencelD 
UInt32 
Boolean 


isochChannelID, 
fwReferencelD, 
refCon, 

clientlsTalker); 


- -> isochChannel ID 
--> fwReferencelD 
--> refCon 
--> clientlsTalker 


Reference to the isochronous channel 
to add the given client to. 

Reference to the client to add to the 
given channel. 

Constant used as a reference by the given 
client's isochronous channel handlers. 

If the given client will be doing the talking, 
cl i entlsTal ker should be set to true. 
Otherwise, cl i entlsTal ker should be 
set to false. 
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DESCRIPTION 

FWAddlsochronousChannel Cl ient adds the given driver as a client to the given 
isochronous channel. The client will be called to perform its role in initializing, 
starting, and stopping the given isochronous channel. The client will also be 
informed of all channel events, such as bus resets. The client can use the 
reference constant ref Con in its isochronous channel handlers as required for 
this channel. If the given client is to be the talker, clientlsTalker must be true; 
otherwise, it must be false. 


8.2.4 FWSetlsochChannelForceStopNotificationProc 

FWSetlsochChannel ForceStopNoti f i cationProc specifies the procedure to call 
when a given channel is forcefully stopped 

OSStatus FWSetlsochChannelForceStopNotificationProc ( 

IsochChannelID isochChannelID, 

FWIsochChannelForceStopNotificationProcPtr 

fwIsochChannelForceStopNotificationProc); 

--> isochChannellD Reference to the isochronous channel to 

set the force stop notification proc for. 

--> fwIsochChannelForceStopNotificationProc 

Procedure to call when the isochronous 
channel is forcefully stopped. 


DESCRIPTION 

FWSetlsochChannel ForceStopNoti fi cati onProc specifies the procedure to call 
when the given channel is forcefully stopped. In some cases the FireWire 
services must stop an isochronous channel without being instructed to do so by 
the owner of the channel. Usually, this will occur if a bus reset is initiated and 
the isochronous bandwidth or channel number cannot be reallocated for the 
isochronous channel. In these cases, the FireWire services will notify the owner 
of the channel that the channel has been stopped by calling a stop notification 
procedure. This procedure will be given the isochronous channel ID in 
i sochChannel ID that has been stopped and the condition in stopCondi ti on for 
which it was stopped. If the required channel bandwidth could not be 
reallocated, stopCondi ti on will be set to kFWIsochChannel NotEnoughBandwi dth. If 
the required channel number could not be reallocated, stopCondi ti on will be set 
to kFWIsochChannelChannelNotAvai 1 able. 


8.2 Isochronous Channel Routines 
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8.2.5 FWInitializelsochronousChannel 

FWIni ti al i zelsochronousChannel calls all of a given isochronous channel's 
clients to initialize the channel for operation. 

OSStatus FWInitializelsochronousChannel ( 

FWCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWInitializelsochronousChannel initializes a given isochronous channel so that 
it may be subsequently started and stopped. The initialization algorithm calls 
each of the given channel's clients twice. The first call does a trial setup; the 
client should return the set of parameters that it can support. Once 
FWInitializelsochronousChannel has determined the appropriate set of channel 
parameters, it calls each client again to do the actual setup. If an error occurs in 
the second call, FWInitializelsochronousChannel returns the error. 


8.2.6 FWReleaselsochronousChannel 

FWRel easelsochronousChannel calls all of a given channel's clients to release the 
resources allocated for the channel. 

OSStatusFWReleaselsochronousChannel ( 

FwCommandObjectID fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWRel easelsochronousChannel releases all the resources allocated for a given 
isochronous channel. The releasing algorithm calls each of the channel's clients 
to release the resources they allocated for the channel. 


8.2.7 FWStartlsochronousChannel 

FWStartlsochronousChannel calls all of a given isochronous channel's clients to 
start the channel. 
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OSStatus FWStartlsochronousChannel ( 

FwCommandObjectlD fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWStartlsochronousChannel causes the given channel to start sending data. It 
calls each listening client first to set them up to listen to the channel. Once all of 
the listeners are ready, FWStartlsochronousChannel calls the talking client to 
start sending data. 


8.2.8 FWStopIsochronousChannel 

FWStopIsochronousChannel calls all of a given isochronous channel's clients to 
stop the channel. 

OSStatus FWStartlsochronousChannel ( 

FwCommandObjectlD fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWStopIsochronousChannel causes the given channel to stop sending data. It 
calls the talking client first to stop sending data through the channel. Once the 
talker stops talking, FWStopIsochronousChannel calls each listening client to stop 
listening. 


8.2.9 FWAIIocatelsochChannelCommandObject 

FWAl 1 ocatelsochChannel CommandObject creates a command object that may be 
used with the various isochronous channel services. 

OSStatus FWAl1ocatelsochChannelCommandObject ( 

FwCommandObjectlD *pFWCommandObjectID); 

<-- pFWCommandObjectID Returned reference to created isochronous 

channel FireWire service command object. 
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DESCRIPTION 

FWA11 ocatelsochChannel CommandObject creates a FireWire service command 
object for the isochronous channel class of FireWire services. In addition to the 
basic set of command object parameters, the command object created by 
FWA11 ocatelsochChannel CommandObject will contain additional parameters 
specific to controlling isochronous channels. 

The basic set of parameters will default to the same values as in 
FWA11 ocateFWCommandObj ect. The fwReferencelD parameter is not used by the 
isochronous channel services and does not need to be set. The isochChannellD 
parameter has no default value and must be set before using the command 
object with any of the isochronous channel services. 

The command object created by FWA11 ocatelsochChannel CommandObject may be 
deallocated with FWDeal 1 ocateFWCommandObject. 


8.2.10 FWSetlsochChannelCommandlsochChannellD 

FWSetlsochChannel CommandlsochChannel ID sets the channel ID that is to be the 

target of a FireWire isochronous channel service. 


OSStatus FWSetlsochChannelCommandlsochChannelID ( 

FWCommandObj ectID fwCommandObjectID 

IsochChannellD isochChannellD); 


--> fwComma ndObj ect ID Command object to set isochChannellD of. 

--> isochChannellD Reference to target of FireWire 

isochronous channel service. 


DESCRIPTION 

FWSetlsochChannel CommandlsochChannel ID sets the IsochChannel ID that is to be 
the target of a FireWire isochronous channel service. There is no meaningful 
default channel ID, so this parameter must be explicitly set before using the 
command object with any FireWire isochronous channel service. 


8.2.11 FWGetlsochChannelCommandlsochChannellD 

FWGetlsochChannel CommandlsochChannel ID returns the channel ID that is to be 
the target of a FireWire isochronous channel service. 
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OSStatus FWGetlsochChannelCommandlsochChannelID ( 

FWCommandObject ID fwCommandObjectID, 

IsochChannellD* pIsochChannellD); 


--> fwCommandObjectID Command object to get isochChannellD of. 

<-- pIsochChannellD Returned reference to target of FireWire 

isochronous channel service. 


DESCRIPTION 

FWGetlsochChannel CommandlsochChannel ID returns the IsochChannel ID that is to 
be the target of a FireWire isochronous channel service. 


8.3 Isochronous Port Routines 


8.3.1 FWAIIocatelsochPortID 

FWAl 1 ocatelsochPortID creates an isochronous port ID that is used by the 
various isochronous port service routines. 

OSStatusFWAl1ocatelsochPortID ( 


IsochPortID 

*pIsochPortID 

DCLProgramID 

delProgramID, 

UInt32 

channelNum, 

UInt32 

speed, 

Boolean 

talking); 

pIsochPortID 

Returned reference to this port for use in 

subsequent isochronous port service calls. 

delProgramID 

DCL program to run with this port. 

channelNum 

Isochronous channel number for this port. 

speed 

Speed at which to run this port. 

talking 

If false, allocate a port for listening; 

otherwise, allocate a port for talking. 
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DESCRIPTION 

FWA1 locatelsochPortID performs the initial setup for an isochronous port. It 
returns an ID that is used as a reference to the port for the isochronous port 
service routines, and it is initialized with the given DCL program, channel 
number, and speed. 


8.3.2 FWDeallocatelsochPortID 

FWDeallocatelsochPortID deallocates an isochronous port ID created by 

FWA1 locatelsochPortID. 

OSStatus FWDeallocatelsochPortID ( 

IsochPortID isochPortlD); 

--> isochPortID Port ID to deallocate. 


DESCRIPTION 

FW Deal locatelsochPortID will deallocate an isochronous port ID allocated with 

FWA1 locatelsochPortID. FWDeallocatelsochPortID will not release the port. This 
should be done with a separate call to FWRel easeLocal IsochronousPort. 


8.3.3 FWAIIocateLocallsochronousPort 

FWAl 1 ocateLocal IsochronousPort allocates an isochronous port on the local 
node. It sets up the port with the DCL program, channel number, speed, and 
direction specified by the given isochPortID. DCL programs are discussed in 
Chapter 9, "Data Stream Control Language." 

OSStatus FWAIIocateLocallsochronousPort ( 

FWCommandObjectlD fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWAl 1 ocateLocal IsochronousPort allocates an isochronous port with the given 
parameters on the local node specified by fwReferencelD. The fwReferencelD 
parameter is used to determine the FWIM for the local node and may be a 
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reference to any entity that is associated with a unique FWIM. The port is set 
up to talk or listen on channel number channelNumata speed determined by 
speed, as specified by the isochPortID. If the port is to be used for listening, 
talking should be false; if it is to be used for talking, tal ki ng should be true. 

The allocated port uses the DCL program referenced by the dcIProgramID set 
for the f sochPortl D. The DCL program is used to control the data stream 
through the allocated port. FWA11 ocateLocal IsochronousPort will cause the DCL 
program to be compiled. Thus, the DCL program command chain should not 
be changed directly until the isochronous port is released. 


8.3.4 FWReleaseLocallsochronousPort 

FWRel easeLocal IsochronousPort releases the resources allocated for an 
isochronous port on the local node. 

OSStatus FWReleaseLocallsochronousPort ( 

FWCommandObjectlD fwCommandObjectID); 

- -> fwCommandOb ject ID Command object controlling this service. 


DESCRIPTION 

FWRel easeLocal IsochronousPort releases all the resources allocated for a given 
local isochronous port. This includes releasing all resources allocated to 
compile the DCL program set up for the local port by a previous call to 
FWA11 ocateLocal IsochronousPort. After the local port has been released, the 
DCL program set up for the port may be directly manipulated and used with a 
subsequent call to FWA11 ocateLocal IsochronousPort. 


8.3.5 FWStartLocallsochronousPort 

FWStartLocal IsochronousPort causes a given local isochronous port to start 
either talking or listening on its isochronous channel. 

OSStatus FWStartLocallsochronousPort ( 

FWCommandObjectlD fwCommandObjectID); 

- - > fwCommandOb ject ID Command object controlling this service. 
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DESCRIPTION 

FWStart Local Isochronous Port causes the local port specified by isochPortIDto 

start either talking or listening on its isochronous channel, using the DCL 
program set up by FWA11 ocateLocal IsochronousPort to control the data stream 
through the port. 


8.3.6 FWStopLocallsochronousPort 

FWStopLocal IsochronousPort causes a given local isochronous port to stop 
either talking or listening on its isochronous channel. 

OSStatus FWStopLocallsochronousPort ( 

FWCommandObjectlD fwCommandObjectID); 

--> fwCommandObjectID Command object controlling this service. 


DESCRIPTION 

FWStopLocal IsochronousPort causes the local port specified by i sochPortID to 

stop talking or listening on its isochronous channel, using the DCL program set 
up by FWA11 ocateLocal IsochronousPort to control the data stream through the 
port. 


8.3.7 FWAIIocatelsochPortCommandObject 

FWAl 1 ocatelsochPortCommandObject creates a command object that may be used 
with the various isochronous port services. 

OSStatus FWAl1ocatelsochPortCommandObject ( 

FwCommandObjectID *pFWCommandObjectID); 

< - - p FWCommandObj ectl D Returned reference to created isochronous 

port FireWire service command object. 


DESCRIPTION 

FWAl 1 ocatelsochPortCommandObject creates a FireWire service command object 
for the isochronous port class of FireWire services. In addition to the basic set of 
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command object parameters, the command object it creates will contain 
additional parameters specific to controlling isochronous ports. 

The basic set of parameters will default to the same values as in 
FWA11 ocateFWCommandOb ject. The isochPortID parameter has no default value 
and must be set before using the command object with any of the isochronous 
port services. 

The command object created by FWA11 ocatelsochPortCommandObject may be 
deallocated with FWDeal 1 ocateFWCommandObject. 


8.3.8 FWSetlsochPortCommandlsochPortlD 

FWSetlsochPortCommandlsochPortID sets the port ID that is to be the target of a 
FireWire isochronous port service. 


OSStatus FWSetlsochPortCommandlsochPortID ( 

FWCommandObjectlD fwCommandObjectlD, 

IsochPortID isochPortID); 


--> fwCommandObjectlD Command object to set isochPortID of. 

--> isochPortID Reference to target of FireWire isochronous 

port service. 


DESCRIPTION 

FWSetlsochPortCommandlsochPortID sets the IsochPortID that is to be the target 
of a FireWire isochronous port service. There is no meaningful default port ID, 
so this parameter must be explicitly set before using the command object with 
any FireWire isochronous port service. 


8.3.9 FWGetlsochPortCommandlsochPortID 

FWGetlsochPortCommandlsochPortID returns the port ID that is to be the target of 
a FireWire isochronous port service. 

OSStatus FWGetlsochPortCommandlsochPortID ( 

FwCommandObjectlD fwCommandObjectlD, 

IsochPortID *pIsochPortID); 
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--> fwCommandObjectlD Command object to set isochPortID of. 

<-- pIsochPortID Returned reference to target of FireWire 

isochronous port service. 


DESCRIPTION 

FWGetlsochPortCommandlsochPortID returns the IsochPortID that is to be the 

target of a FireWire isochronous port service. 


8.4 Miscellaneous Isochronous Routines 


8.4.1 FWGetFWIsochResourceManagerlD 

FWGetFWIsochResourceManagerlD returns a reference to the isochronous resource 
manager for a given bus. 


OSStatus FWGetFWIsochResourceManagerlD ( 

FWReferencelD fwReferencelD, 

FWIsochResourceManagerlD *pFWIsochResourceManagerID); 


--> fwReferencelD Reference to bus to get isochronous 

resource manager ID for. 

<-- pFWIsochResourceManagerlD Returned ID of isochronous resource 

manager. 


DESCRIPTION 

FWGetFWIsochResourceManagerlD returns in pFWIsochResourceManagerlD a 

reference to the isochronous resource manager for the FireWire bus referenced 
by fwReferencelD. The returned reference can be used most places where other 
references can be used (such as asynchronous transaction and configuration 
ROM routines). The pFWIsochResourceManagerlD parameter references the 
current isochronous resource manager device on the FireWire bus. The 
FireWire services maintains this reference across bus resets even if the 
isochronous resource manager moves to a different device. 
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The Data Stream Control Language (DCL) is a set of commands that control 
data flow into or out of a data stream. A collection of DCL commands is 
connected together into a linked list to make a DCL program that can be 
assigned to a particular data stream such as one associated with an isochronous 
channel. This chapter describes the programming interface to the DCL 
commands supported by the Mac OS FireWire services. 


9.1 Structures, Data Types, and Constants 


9.1.1. DCLCommand 


struct DCLCommandStruct 


DCLCommandPtr 
UI n 13 2 
UI n 13 2 
UI n 13 2 


pNextDCLCommand; 
compi1erData; 
opcode; 
operandsll]; 


typedef struct DCLCommandStruct DCLCommand 

*DCLCommandPtr; 


pNextDCLCommand 
compi1erData 
opcode 
operands 


Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL command. 
Operands of DCL command. 
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9.1.2. DCLTransferPacket 


struct DCLTransferPacketStruct 
{ 

DCLCommandPtr 

UInt32 

UInt32 

Ptr 

UInt32 

) 

typedef struct DCLTransferPacke 

pNextDCLCommand 

compi1erData 
opcode 

buffer 

si ze 


pNextDCLCommand; 
compi1erData ; 
opcode; 
buffer; 
size; 

ruct DCLTransferPacket 

*DCLTransferPacketdPtr; 

Link to next DCL command in 
program. 

DCL compiler's private data. 

Opcode specifying type of DCL 
command. 

Pointer to buffer to send/receive 
packet from/into. 

Size of data to send/receive. 


9.1.3 DCLTransferBuffer 


struct DCLTransferPacketStruct 


DCLCommandPtr 

UInt32 

UInt32 

Ptr 

UInt32 
HInt16 
UI n 116 
UInt32 


pNextDCLCommand; 
compi1erData; 
opcode; 
buffer; 
size; 

packetSize; 
reserved; 
bufferOffset; 


typedef struct DCLTransferPacketStruct DCLTransferPacket 

*DCLTransferPacketdPtr; 
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pNextDCLCommand 

compi1erData 
opcode 

buffer 

si ze 

packetSize 
bufferOffset 


Link to next DCL command in 
program. 

DCL compiler's private data. 

Opcode specifying type of DCL 
command. 

Pointer to buffer to send/ 
receive data from/into. 

Size of buffer. 

Size of packets. 

Amount of data sent/received. 


9.1.4. DCLCallProc 


struct DCLCal1ProcStruct 
{ 

DCLCommandPtr 

UInt32 

UInt32 

DCLCal1 CommandProcPtr 
UInt32 

); 

typedef struct DCLCal1ProcStruct 


pNextDCLCommand 

compi1erData 
opcode 

proc 

procData 

9.1.5. DCLLabel 


pNextDCLCommand; 
compi1erData; 
opcode; 
proc; 
procData; 

DCLCal1Proc 
*DCLCal1ProcPtr; 

Link to next DCL command in 
program. 

DCL compiler's private data. 
Opcode specifying type of DCL 
command. 

Pointer to proc to be called. 
Proc's private data. 


struct DCLLabelStruct 
{ 

DCLCommandPtr pNextDCLCommand; 

UInt32 compi1erData; 
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UIn 132 

); 

typedef struct DCLLabelStruct 


pNextDCLCommand 
compi1erData 
opcode 


opcode; 

DCLLabel 
*DCLLabel Ptr; 

Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL command. 


9.1.6. DCLJump 


struct DCLJumpStruct 


DCLCommandPtr 
UInt32 
UInt32 
DCLLabelPtr 


pNextDCLCommand; 
compi1erData ; 
opcode; 

pJumpDCLLabel ; 


typedef struct DCLJumpStruct 


DCLJump 
*DCLJumpPtr; 


pNextDCLCommand 
compi1erData 
opcode 

pJumpDCLLabel 


Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL command. 
Pointer to DCL label to jump to. 


9.1.7 DCLSetTagSyncBits 


struct DCLSetTagSyncBitsStruct 


DCLCommandPtr 
UInt32 
UI n 132 
UI n 116 
UI n 116 


pNextDCLCommand; 
compi1erData; 
opcode; 
tagBits; 
syncBits 


typedef struct DCLSetTagSyncBitsStruct DCLSetTagSyncBits 

*DCLSetTagSyncBitsPtr; 
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pNextDCLCommand 
compi1erData 
opcode 
tagBits 
syncBits 


Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL command. 
Tag bits to use for sending packets. 

Sync bits to use for sending packets. 


9.1.8 DCLUpdateDCLList 


struct DCLUpdateDCLListStruct 

{ 

DCLCommandPtr 

UInt32 

UInt32 

DCLCommandPtr 

UInt32 


pNextDCLCommand; 
compi1erData; 
opcode; 

*dclCommandList; 
numDCLCommands; 


typedef struct DCLUpdateDCLListStruct DCLUpdateDCLList 

*DCLUpdateDCLListPtr; 


pNextDCLCommand 
compi1erData 
opcode 

delCommandList 
numDCLCommands 


Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL 
command. 

List of DCL commands to update. 
Number of DCL commands in list. 


9.1.9 DCLTimeStamp 


struct DCLTimeStampStruct 
{ 

DCLCommandPtr 

UInt32 

UInt32 

UInt32 

}; 

typedef struct DCLTimeStampStruct 


pNextDCLCommand; 
compi1erData; 
opcode; 
timeStamp; 

DCLTimeStamp 

*DCLTimeStampPtr; 
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pNextDCLCommand 
compi1erData 
opcode 

timeStamp 


Link to next DCL command in program. 
DCL compiler's private data. 

Opcode specifying type of DCL 
command. 

Time stamp for this DCL in cycle 
timer format. 


9.1.10 DCL Types 


typedef Kernel ID DCLProgramID; 

typedef void (DCLCal 1 CommandProc) ( 

DCLCommandPtr pDCLCommand); 

typedef DCLCal1CommandProc *DCLCal1CommandProcPtr; 

typedef OSStatus (DCLProgramStartProc) ( 

DCLProgramID delProgramID); 

typedef DCLProgramStartProc *DCLProgramStartProcPtr; 

typedef OSStatus (DCLProgramStopProc) ( 

DCLProgramID delProgramID); 

typedef DCLProgramStopProc *DCLProgramStopProcPtr; 


typedef OSStatus (DCLProgramReleaseProc) ( 

DCLProgramID delProgramID); 

typedef DCLProgramReleaseProc *DCLProgramReleaseProcPtr; 


typedef OSStatus (DCLCompile 

DCLProgramID 
UInt32 

DCLCommandPtr 

UInt32 

typedef DCLCompi1erNotificationProc 

DCLProgramID 
DCLCal1CommandProc 

DCLProgramStartProc 


■ NotificationProc) ( 
delProgramID, 
notificationType, 

*dcl CommandLi st, 
numDCLCommands); 

*DCLCompi1erNotificationProcPtr; 

Reference to a DCL program. 

Type of proc that gets called by 
a DCLCallProc command. 

Type of proc used to start a 
compiled DCL program. 
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DCLProgramStopProc 
DCLProgramReleaseProc 
DCLCompilerNotificationProc 


Type of proc used to stop a 
compiled DCL program. 

Type of proc used to release a 
compiled DCL program 
Type of proc used to notify a 

DCL compiler of a change to a 
DCL command. 


9.1.11 DCL Constants 


enum 


klnvalidDCLProgramlD 

); 

klnvalidDCLProgramlD 


enum 

{ 

kFWDCLImmediateEvent 
kFWDCLCycleEvent 

); 

kFWDCLImmediateEvent 
kFWDCLCycleEvent 


enum 

I 

kFWDCLOpDynamicFlag 
kFWDCLOpVendorDefinedFlag 
kFWDCLOpFlagMask 
kFWDCLOpFlagPhase 

); 


= 0 


If a DCLProgramI D is equal to 
this constant, it is invalid. 


= 0 , 
= 1 


Specifies that an event occurs 
immediately. 

Specifies that an event occurs 

on a particularisochronous cycle. 


= (1 « 16 ), 

= (1 « 17 ), 

= BitRange ( 16 , 31 ), 

= BitRangePhase ( 16 , 31 ) 
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kFWDCLOpDynami cFl ag 

kFWDCLOpVendorDefinedFlag 

k FW DC LOp FIagMask 

enum 

f 

kDCLInvalidOp 

kDCLSendPacketStartOp 

kDCLSendPacketWithHeaderStartOp 

kDCLSendPacketOp 

kDCLSendBufferOp 

kDCLReceivePacketStartOp 

kDCLReceivePacketOp 

kDCLReceiveBufferOp 

kDCLCal1ProcOp 

kDCLLabelOp 

kDCLJumpOp 

kDCLSetTagSyncBitsOp 
kDCLUpdateDCLListOp 
kDCLT fmeStampOp 

) ; 

kDCLInvalidOp 
kDCLSendPacketStartOp 


kDCLSendPacketWithHeaderStartOp 


kDCLSendPacketOp 

kDCLSendBufferOp 

kDCLReceivePacketStartOp 


kDCLReceivePacketOp 


Specifies that the DCL command may 
be modified. 

Specifies that the DCL command 

opcode is a vendor-defined opcode. 
Mask of all flag bits in opcode. 


= 0 . 
= 1 , 
= 2 . 
= 3. 
= 4 
= 5 . 
= 6 . 
= 7. 
= 8 . 
= 9 . 
= 10 
= 11 
= 12 
= 13 


An invalid DCL command opcode. 

DCL specifying the first part of 
a packet buffer to be sent to a 
data stream. 

DCL specifying the first part of 
a packet buffer with header to 
be sent to a data stream. 

DCL specifying part of a packet 

buffer to be sent to a data stream. 

DCL specifying a buffer to be 
sent to a data stream. 

DCL specifying the first part of 
a packet buffer to be received 
from a data stream. 

DCL specifying part of a packet 
buffer to be received from a 
data stream. 
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kDCLReceiveBufferOp 

kDCLCal1ProcOp 
kDCLLabelOp 

kDC LJumpOp 

kDCLSetTagSyncBitsOp 

kDCLUpdateDCLListOp 
kDCLTimeStampOp 

enum 


DCL specifying a buffer to 

receive data from a data stream. 

DCL specifying a proc to be called. 

DCL specifying a location that 
can be jumped to. 

DCL specifying another DCL to jump to. 

DCL specifying the tag and sync 
bits for packets to be sent to a 
data stream. 

DCL specifying a list of DCLs to 
be updated. 

DCL specifying a time stamp to be set. 


kFWDCLI rival i dNoti fi cati on = 0, 
kFWDCLUpdateNotification = 1, 
kFWDCLModifyNotification = 2 


kFWDCLInvalidNotification 
kFWDCLUpdateNotification 

kFWDCLModifyNotification 


An invalid DCL program notification. 
Notification specifying that the given 
DCL command must be updated. 
Notification specifying that the given 
DCL command must be modified. 


9.2 Data Stream Control Language Overview 


Data Stream Control Language commands are connected together into a linked 
list to make a program that can be assigned to a particular data stream. The 
default execution order of a DCL program is to start with the first DCL 
command in the program and to follow the DCL command links. This 
execution order may be changed by using DCL jump commands. The linked 
list of DCL commands must be ni 1 -terminated to indicate the end of the DCL 
program. If a loop is required, the DCL jump command must be used. 

The DCL command language is designed to be simple, extensible, and 
compilable into DMA programs. DCL programs will be created by drivers and 
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will be compiled by FWIMs into DMA programs. More complex DCL 
commands may be added in the future (e.g., kDCLRecei vePixMap). These DCL 
commands may be directly supported by some DMA architecture or may be 
translated into simpler DCL commands. The FireWire services provide routines 
to translate complicated DCL programs into simpler ones. Thus, a FWIM does 
not have to be able to compile all DCL commands. A FWIM is only required to 
support a core set of DCL commands that may be used to translate a more 
complicated DCL program. This core set is composed of the following DCL 
commands: 

kDCLSendPacketWithHeaderStartOp 

kDCLSendPacketOp 

kDCLReceivePacketStartOp 

kDCLReceivePacketOp 

kDCLCal1ProcOp 

kDCLLabelOp 

kDCLJumpOp 

kDCLUpdateDCLListOp 

In addition to providing support for the core DCL command set, a FWIM must 
support the kFWDCLOpDynami cFl ag being set for the core DCL commands. 

To compile a DCL program, a FWIM starts with the first DCL command in the 
program. The FWIM will then follow the links from one DCL command to 
another, compiling each one into DMA commands. The FWIM should only 
follow the command links and not follow DCL jump commands to their 
destinations. The FWIM will be done when it reaches a nil command link. If the 
FWIM reaches a DCL command that it cannot compile, it will use the FireWire 
services translation facilities to translate the DCL program into one with 
simpler DCL commands. 

If a FWIM does not directly support a given DCL program, it may request the 
FireWire services to translate the DCL program into a simpler one by calling 
FWTransl ateDCLProgram. In this case, there may be two DCL programs, the 
original and the translated. The original program will operate under the 
control of the FireWire services, and the translated program will be compiled 
by the FWIM into DMA commands and will operate under control of the 
FWIM. 
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9.3 Data Stream Control Language Client Services 


9.3.1 FWCreateDCLProgram 

FWCreateDCLLProgram returns a DCL program ID to be used to construct a DCL 
program. 

OSStatus FWCreateDCLProgram ( 

DCLProgramID *pDCLProgramID); 

<-- pDCLProgramlD Created DCLProgramID. 


DESCRIPTION 

Before a DCL program may be constructed, FWCreateDCLLProgram must be 
called to create a DCLProgramID to reference the DCL program. The returned 
DCLProgramID is used in all subsequent DCL calls to reference the DCL program 
being constructed. 


9.3.2 FWDisposeDCLProgram 

FWDi sposeDCLLProgram disposes of a DCLProgramID. 

OSStatus FWDisposeDCLProgram ( 

DCLProgramID delProgramID); 

--> del ProgramID DCLProgramID to dispose of. 


DESCRIPTION 

When a driver needs to dispose of a DCL program, it calls FWDi sposeDCLProgram 
to release the resources allocated by FWCreateDCLProgram. FWDi sposeDCLProgram 

will not deallocate any of the DCL commands in the program or any of the 
buffers specified by those commands; this deallocation is the responsibility of 
the driver. 
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9.3.3 FWSetDCLProgramStart 

FWSetDCLProgramSta rt sets the first DCL command in a DCL program. 


OSStatus FWSetDCLProgramStart 

DCLProgramID 
DCLCommandPtr 


( 

delProgramID, 
pDCLCommand); 


--> delProgramID 
--> pDCLCommand 


DCLProgramI D to set start of. 

First DCL command of program. 


DESCRIPTION 

FWSetDCLProgramStart sets the first DCL command of a DCL program. This will 
be the first DCL command executed when the DCL program is run. Additional 
DCL commands may be linked into the program after FWSetDCLProgramStart is 
called but before the DCL program is run. 


9.3.4 FWGetDCLProgramStart 

FWGetDCLProgramSta rt returns the first DCL command in a DCL program. 


OSStatus FWGetDCLProgramStart 

DCLProgramID 
DCLCommandPtr 


( 

delProgramID, 
*ppDCLCommand); 


--> delProgramID 
<-- ppDCLCommand 


DCLProgramI D to get start of. 

First DCL command of program. 


DESCRIPTION 

FWGetDCLProgramStart returns the first DCL command of a DCL program as set 
by FWSetDCLProgramStart. This routine is typically used by a FWIM to get the 
start of the linked list of DCL commands it must compile. 


9.3.5 FWSetDCLProgramStartEvent 

FWSetDCLProgramSta rtEvent sets an event for the DCL program to start on. 
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OSStatus FWSetDCLProgramSt 

DCLProgramID 
UInt32 
UInt32 
UInt32 

--> dcIProgramID 
--> startEvent 
--> startEventState 
--> startEventStateMask 


artEvent ( 

delProgramID, 
startEvent, 
startEventState, 
startEventStateMask); 

DCLProgramID to set start event of. 
Type of event to start on. 

State of event to start on. 

Mask of relevent bits in 

startEventState. 


DESCRIPTION 

FWSetDCLProgramStartEvent sets an event to start the DCL program on. These 
events include klmmedi ateEvent and kCycl eEvent. 

The klmmedi ateEvent specifies that the DCL program should start immediately 
upon starting the data stream associated with the DCL program; this is the 
default starting event. 

The kCycleEvent specifies that the DCL program should wait until the specified 
cycle number has occurred. The cycle number to start on is specified in 
startEventState. The number placed in startEventState is the full 32-bit cycle 
time but the lower-order 12 cycle offset bits are ignored. The 
startEventStateMask specifies the relevent bits in startEventState. If a driver 
wishes a DCL program to start exactly on cycle 0, it should set 
startEventStateMask to OxFFFF FFFF (the lower 12 bits of the mask are ignored 
and assumed to be 0 because the cycle offset is always masked out). If a driver 
wishes a DCL program to start only on cycle count 0 but doesn't care about the 
seconds count, it should set startEventStateMask to OxOlFF FFFF. 


9.3.6 FWGetDCLProgramStartEvent 

FWGetDCLProgramStartEvent returns the event for the DCL program to start on. 


OSStatus 

DCLProgramID 

UInt32 

UInt32 

UInt32 


FWGetDCLProgramStartEvent ( 

delProgramID, 
*pStartEvent, 
*pStartEventState, 
*pStartEventStateMask); 


9.3 Data Stream Control Language Client Services 


187 



CHAPTER 9 


Data Stream Control Language 


--> delProgramID 
<-- pStartEvent 
<-- pStartEventState 
<-- pStartEventStateMask 


DCLProgramID to get start event of. 
Type of event to start on. 

State of event to start on. 

Mask of relevent bits in 

sta rtEventState. 


DESCRIPTION 

FWGetDCLProgramSta rtEvent returns the start event information for the given 
DCL program. This routine is typically used by a FWIM to determine what 
event to start a DCL program on. 

If the event is a kCycl eEvent, the FWIM should ignore the lower 12 bits of 
startEventState. Any other bits that are masked out by a 0 bit in 
sta rtEventStateMask may be arbitrarily selected by the FWIM. For example, if a 
FWIM's hardware supports starting on a particular cycle number but must 
specify both the seconds and the cycle count, and if a driver has masked out 
the upper 7bits of the seconds count in startEventStateMask, the FWIM may 
program its DMA engine to start on any seconds count. The only requirement 
in this case is that the FWIM program its DMA engine to start on a cycle whose 
cycle count (bits 7 to 19) matches the cycle count (bits 7 to 19) in the 
startEventState. Ideally, the FWIM will pick a seconds count that is not too far 
into the future from the current seconds count being sent by the cycle master. 
Otherwise, the DMA may not start for up to 128 seconds. 


9.3.7 FWModifyDCLJump 

FWModi fyDCLJump is used to modify a DCL jump command in a DCL program 
that is currently running. 


OSStatus FWModifyDCLJump 

DCLProgramID 
DCLJumpPtr 
DCLLabelPtr 


( 

delProgramID, 
pDCLJump, 
pDCLLabel); 


--> del ProgramID 

--> pDCLJump 
--> pDCLLabel 


DCLProgramID of DCL program to modify 
jump for. 

Pointer to DCL jump command to modify. 
Pointer to new destination DCL labelof 
the DCL jump command. 
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DESCRIPTION 

FWModi fyDCLJump sets a new DCL label destination of the given DCL jump 
command. This routine may be called while the DCL program is in progress 
and may be called in any environment except primary interrupt level. 
Typically, a driver will call this to dynamically change the execution order of a 
DCL program. Because the updated DCL jump command must be recompiled, 
the driver can't just change the DCL jump command directly. The driver must 
call FWModi fyDCLJump so that notification can be sent to the DCL compiler 
(usually, a FWIM). In addition, the driver must have set the 
kFWDCLOpDynami cFl ag in the DCL jump command opcode when the driver first 
constructed the DCL program. 

A driver may use this call if it needs to regularly update buffers being 
transmitted on a data stream. The driver can place a DCL jump command after 
every DCL send-packet command. If the buffer following a DCL jump 
command contains fresh data, the DCL jump command will simply jump to a 
DCL label before that buffer. If the buffer following a DCL jump command 
contains stale data, the DCL jump command will jump to a DCL label before a 
DCL call proc command that will call some routine that will notify the driver 
that its buffers have underrun. Whenever the driver updates a buffer, it will 
call FWModi fyDCLJump to set the DCL jump command before the updated buffer 
to point to a DCL label before the buffer. The driver will then also call 
FWModi fyDCLJump to set the DCL jump command after the buffer to point to a 
DCL label before the DCL call proc command that notifies the driver of buffer 
underruns. If the driver gets behind in updating its buffers, and the DCL 
program progresses past the last updated buffer, the DCL program will jump 
to the DCL call proc command and notify the driver that its buffers have 
underrun. 

9.3.8 FWUpdateDCLList 

FWUpdateDCLLi st is used to update a list of DCL commands. 

OSStatus FWUpdateDCLList ( 

DCLProgramlD delProgramID, 

DCLCommandPtr *dclCommandList, 

UIn132 numDCLCommands ); 
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--> delProgramID 

--> delCommandList 
--> numDCLCommands 


DCLProgramI D of DCL program to update 
DCL list for. 

List of DCL commands to update. 
Number of DCL commands in list. 


DESCRIPTION 

FWUpdateDCLLi st is used to update a list of DCL commands. The updating 
service instructs the FWIM to bring the state of the given DCL commands up to 
date with respect to the DMA engine. This may include flushing processor 
caches or updating the bufferOffset field of a DCLTransferBuffer record to 
reflect the current buffer offset. 

DCL command updating is used to ensure that the data used by the higher 
level clients matches the data used by the lower level hardware. DCL 
command updating is similar to the use of Checkpoi ntIO for updating DMA 
buffers. Usually, when DCL commands are updated, the FWIM will call 

CheckpointIO. 

When using a DCL program to receive data, the higher level clients should 
update DCL commands before reading any data from the commands. When 
using a DCL program to transmit data, the higher level clients should update 
DCL commands after writing data to the commands. 

Generally, the only DCL commands that need updating are commands with 
changing values such as all of the transfer commands. The transfer buffers 
must be updated to stay in synch with the hardware. In addition, the 
bufferOffset field of the DCLT ransferBuffer record must be updated before its 
contents can be considered valid. 

When a DCL program is first constructed, it will be up to date. Thus, when 
using a non-looping DCL program for transmitting, the transfer buffers do not 
need to be updated. 

This routine may be called in any execution environment other than primary 
interrupt level. 

9.3.9 FWModifyDCLList 

FWModi fyDCLLi st is used to specify a list of DCL commands that have been 
modified. 
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OSStatus 

DCLProgramID 

DCLCommandPtr 

UInt32 


FWModi fyDCLLi st ( 

delProgramlD, 
*dclCommandList, 
numDCLCommands); 


--> delProgramlD 
--> delCommandList 
--> numDCLCommands 


DCLProgramID of DCL program to 
modify DCL list for. 

List of DCL commands that have been 
modified. 

Number of DCL commands in list. 


DESCRIPTION 

FWModi fyDCLLi st is used to specify a list of DCL commands that have been 
modified. When a high level client wishes to modify a set of DCL commands 
within a DCL program, it must first set the kFWDCLOpDynami cFl ag within the 
opcode of each DCL command to be modified. The high level client must do 
this during the construction of the DCL program. This allows the FWIM to 
prepare in advance for any DCL commands that may be modified while the 
DCL program is executing. 

During the execution of the DCL program, the high level client may then 
modify some of the fields of the DCL commands. It then notifies the DCL 
program compiler of the changes by passing the list of modified DCL 
commands into a call to FWModi fyDCLLi st. The high level client may not modify 
the pNextDCLCommand or opcode fields. 

Note that a FWIM need only support DCL command modifications to the core 
set of DCL commands. If a client wishes to be able to modify a non-core DCL 
command, the FWIM may have to translate the DCL program even if the 
FWIM can directly support the DCL command without the 

kFWDCLOpDynami cFI ag set. 

This routine may be called in any execution environment other than primary 
interrupt level. 
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9.4 Data Stream Control Language FWIM Services 


9.4.1 FWSetDCLProgramEngineData 

FWSetDCLProgramEngi neData sets a 32-bit data field for use by the software 
running and / or compiling the DCL program. 


OSStatus FWSetDCLProgram 

DCLProgramID 
UIn 132 

--> del ProgramID 
- -> del EngineData 


^ngineData ( 
delProgramID, 
delEngineData ); 

DCLProgramI D to set engine data of. 
Data used by DCL program engine. 


DESCRIPTION 

FWSetDCLProgramEngi neData is typically used by the FWIM compiling a DCL 
program to store its private information about the DCL program. For example, 
a FWIM might store a pointer to the beginning of the DMA program that it 
compiled from the DCL program. Alternatively, a FWIM might store a pointer 
to a data structure that contains the start of the DMA program and the DMA 
channel being used for the DCL program. The engine data will typically be set 
when the FWIM first compiles the DCL program and will later be retrieved 
when the FWIM is told to start or stop the DCL program. 


9.4.2 FWGetDCLProgramEngineData 

FWGetDCLProgramEngi neData gets a 32-bit data field for use by the software 
running and / or compiling the DCL program. 


OSStatus FWGetDCLProgram 

DCLProgramID 
UIn 132 

--> del ProgramID 
<-- pDCLEngineData 


^ngineData ( 
delProgramID, 

*pDCLEngineData); 

DCLProgramI D to get engine data of. 
Data used by DCL program engine. 
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DESCRIPTION 

FWGetDCLProgramEngi neData returns the 32-bit data passed in to 
FWSetDCLProgramEngineData. 


9.4.3 FWSetDCLProgramCompilerNotificationProc 

FWSetDCLProgramCompi 1 erNoti f i cati onProc sets the update notification routine 
for a DCL program. 

OSStatus FWSetDCLProgramCompi1erNotificationProc ( 

DCLProgramID delProgramID, 

DCLCompilerNotificationProcPtr delCompi1erNotificationProc); 

--> del ProgramID DCLProgramID to set notification proc of. 

- -> del Compi 1 erNoti fi cati onProc Proc to call on DCL program updates. 


DESCRIPTION 

FWSetDCLProgramCompi 1 erNoti fi cati onProc sets the routine to call when a DCL 
program is updated. 

If a high level client wishes to change a DCL command while a DCL program 
is running, the compiler must be notified to change the corresponding DMA 
commands. This may happen if a client wishes to change the destination of a 
DCL jump command by calling FWModi fyDCLJump. The FWModifyDCLJump 
routine will call the DCL program's notification routine and pass it the DCL 
jump command that has been modified. The notification routine must then 
make any changes necessary to change the target of the jump command. 
Typically, this will involve changing the destination of a DMA branch 
command. The notification routine is also used to send DCL command update 
notifications from the clients. 

The notification routine has the following format: 


typedef OSStatus (DCLCom 
DCLProgramID 
UInt32 

DCLCommandPtr 

UInt32 


i1erNotificationProc) ( 
delProgramID, 
notificationType 
*dclCommandList, 
numDCLCommands); 
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--> dcIProgramID DC LProg ram ID of notification. 

--> notificationType Type of notification. May be 

kFWDCLUpdateNotification or 
kFWDCLModi fyNoti ft cati on. 

--> del CommandLi st List of DCL commands that are a part of 

the notification 

--> numDCLCommands Number of DCL commands in list. 

All FWIMs must support this notification mechanism for modifying DCL jump 
commands and updating other DCL commands. 

9.4.4 FWGetDCLProgramCompilerNotificationProc 

FWGetDCLProgramCompi 1 erNoti f i cati onProc gets the update notification routine 
for a DCL program. 

OSStatus FWGetDCLProgramCompi1erNotificationProc ( 

DCLProgramID dcIProgramID, 

DCLCompi1erNotificationProcPtr *pDCLCompilerNotificationProc); 

--> dcIProgramID DCLProgramID to get notification proc of. 

< - - pDCLCompi 1 erNoti f i cati onProc Proc to call on DCL program updates. 


DESCRIPTION 

FWGetDCLProgramCompi 1 erNoti fi cati onProc returns the routine to call when a 
DCL program is updated. This routine is used internally by the FireWire 
services. It will typically not be used outside the FireWire services but is 
provided for convenience. 

9.4.5 FWSetDCLProgramStartProc 

FWSetDCLProgramSta rtProc sets the routine to use to start theDCL program. 

OSStatus FWSetDCLProgramStartProc ( 

DCLProgramID dcIProgramID, 

DCLProgramStartProcPtr dclProgramStartProc); 

--> dcIProgramID DCLProgramID to set start proc of. 

--> dclProgramStartProc Proc to call to start a DCL program. 
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DESCRIPTION 

FWSetDCLProgramStartProc sets the routine to call to start a DCL program. When 
FWStartDCLProgram is called to start a DCL program, the start proc for the DCL 
program is called (if it is set). If a DCL program has been translated, multiple 
start procs may be called (one for the original DCL program and one for the 
translated DCL program). The first start proc will most likely initiate some 
code in the FireWire services. The FireWire services code will do some setup 
and call the start proc for the translated DCL program. This start proc will most 
likely initiate some code in the FWIM, which will program the DMA engines to 
begin running. 

9.4.6 FWGetDCLProgramStartProc 

FWGetDCLProgramStartProcProc gets the routine to use to start theDCL program. 

OSStatus FWGetDCLProgramStartProc ( 

DCLProgramlD delProgramID, 

DCLProgramStartProcPtr *pDCLProgramStartProc); 

--> del ProgramlD DCLProgramlD to get start proc of. 

<-- pDCLProgramStartProc Proc to call to start DCL programs. 


DESCRIPTION 

FWGetDCLProgramStartProc returns the routine to call to start a DCL program. 
This routine is used internally by the FireWire services. It will typically not be 
used outside the FireWire services but is provided for convenience. 

9.4.7 FWSetDCLProgramStopProc 

FWSetDCLProgramStopProc sets the routine to use to stop theDCL program. 

OSStatus FWSetDCLProgramStopProc ( 

DCLProgramlD delProgramID, 

DCLProgramStopProcPtr dclProgramStopProc); 

--> dcIProgramID DCLProgramlD to set stop proc of. 

--> dclProgramStopProc Proc to call to stop a DCL program. 
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DESCRIPTION 

FWSetDCLProgramStopProc sets the routine to call to stop a DCL program. When 
FWStopDCLProgramis called to stop a DCL program, the stop proc for the DCL 
program is called (if it is set). If a DCL program has been translated, multiple 
stop procs may be called (one for the original DCL program and one for the 
translated DCL program). The first stop proc will most likely initiate some 
code in the FireWire services. The FireWire services code will take some 
internal action to stop and call the stop proc for the translated DCL program. 
This stop proc will most likely initiate some code in the FWIM, which will 
program the DMA engines to stop running. 


9.4.8 FWGetDCLProgramStopProc 

FWGetDCLProgramStopProcProc gets the routine to call to stop a DCL program. 


OSStatus FWGetDCLProgramStopProc ( 

DCLProgramID delProgramID, 

DCLProgramStopProcPtr *pDCLProgramStopProc); 


--> dcIProgramID DCLProgramID to get stop proc of. 

<-- pDCLProgramStopProc Proc to call to stop DCL programs. 


DESCRIPTION 

FWGetDCLProgramStopProc returns the routine to call to stop a DCL program. 
This routine is used internally by the FireWire services. It will typically not be 
used outside the FireWire services but is provided for convenience. 


9.4.9 FWSetDCLProgramReleaseProc 

FWSetDCLProgramRel easeProc sets the routine to use to release resources 
allocated for theDCL program. 


OSStatus FWSetDCLProgramReleaseProc ( 

DCLProgramID dcIProgramID, 

DCLProgramReleaseProcPtr delProgramReleaseProc); 


--> dcIProgramID DCLProgramID to set release proc of. 

--> del ProgramRel easeProc Proc to call to release a DCL program. 
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DESCRIPTION 

FWSetDCLProgramRel easeProc sets the routine to call to release resources 
allocated for a DCL program. 

When FWRel easeDCLProgram is called to release the resources allocated for a DCL 
program, the release proc for the DCL program is called (if it is set). If a DCL 
program has been translated, multiple release procs may be called (one for the 
original DCL program and one for the translated DCL program). The first 
release proc will most likely initiate some code in the FireWire services. The 
FireWire services code will release its internal resources allocated for the DCL 
program and call the release proc for the translated DCL program. This release 
proc will most likely initiate some code in the FWIM, which will release its own 
resources allocated for the DCL program. 


9.4.10 FWGetDCLProgramReleaseProc 

FWGetDCLProgramRel easeProcProc gets the routine to call to release the resources 
allocated for a DCL program. 


OSStatus FWGetDCLProgram 

DCLProgramlD 

DCLProgramReleaseProcPtr 

--> delProgramlD 

<-- pDCLProgramReleaseProc 


ReleaseProc ( 
delProgramlD, 

*pDCLProgramReleaseProc); 

DCLProgramlD to get stop proc of. 

Proc to call to release DCL programs. 


DESCRIPTION 

FWGetDCLProgramRel easeProc returns the routine to call to release the resources 
allocated for a DCL program. This routine is used internally by the FireWire 
services. It will typically not be used outside the FireWire services but is 
provided for convenience. 


9.4.11 FWTranslateDCLProgram 

FWTransl ateDCLProgram translates a complex DCL program into a simpler DCL 
program. 
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OSStatus 

DCLProgramID 
DCLProgramID 


FWTranslateDCLProgram ( 

delProgramID, 

*pTranslatedDCLProgramID); 


--> dcIProgramID DCLProgramID of DCL program to translate. 

<-- pTransl atedDCLPrograml D Returned DCLProgramID of simpler, 

translated DCL program. 


DESCRIPTION 

FWTransl ateDCLProgram translates a DCL program with complex DCL 
commands into a DCL program that only uses the required core set of DCL 
commands. This routine is typically called by a FWIM that has been given a 
DCL program with some DCL commands that the FWIM does not directly 
support (e.g., kDCLRecei veBuffer). The translated DCL program will be 
returned in p T r a n s 1 a t e d D C L P r o g r a m ID, and the FWIM should be able to compile 
the translated DCL program since it will only contain the required DCL 
commands. 

If a FWIM calls FWTransl ateDCLProgram, it should use the translated program to 
set its engine data, notification, start, stop, and release procs. It should use the 
original program when calling FWStartDCLProgram, FWStopDCLProgram, or 
FWReleaseDCLProgram. 


9.4.12 FWStartDCLProgram 

FWStartDCLProgram initiates the execution of a DCL program. 

OSStatus FWStartDCLProgram ( 

DCLProgramID dcIProgramID); 

--> dcIProgramID DCLProgramID of DCL program to start. 


DESCRIPTION 

FWSta rtDCLProgram initiates the execution of a DCL program. FWSta rtDCLProgram 
calsl the start proc set for the DCL program with FWSetDCLProgramStartProc. If 
no translation has been performed on the DCL program, FWStartDCLProgram 
will typically call a routine in the FWIM to program the DMA engines to begin 
running the DMA program compiled from the DCL program. If translation has 
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been performed on the DCL program, FWStartDCLProgram will typically call a 
routine in the FireWire services, which will do some setup and call 
FWStartDCLProgram on the translated DCL program. This second call to 
FWStartDCLProgram will typically call into the FWIM. 


9.4.13 FWStopDCLProgram 

FWStopDCLProgram stops the execution of a DCL program. 

OSStatus FWStopDCLProgram ( 

DCLProgramID delProgramID); 

--> del ProgramID DCLProgramID of DCL program to stop. 


DESCRIPTION 

FWStopDCLProgram stops the execution of a DCL program. FWStopDCLProgram calls 
the stop proc set for the given DCL program with FWSetDCLProgramStopProc. If 
no translation has been performed on the DCL program, FWStopDCLProgram will 
typically call a routine in the FWIM to program the DMA engines to stop 
running the DMA program compiled from the DCL program. If translation has 
been performed on the DCL program, FWStopDCLProgram will typically call a 
routine in the FireWire services, which will take some internal action to stop 
and call FWStopDCLProgram on the translated DCL program. This second call to 
FWStopDCLProgram will typically call into the FWIM. 


9.4.14 FWReleaseDCLProgram 

FWRel easeDCLProgram releases the resources allocated for a DCL program. 

OSStatus FWReleaseDCLProgram ( 

DCLProgramID delProgramID); 

--> del ProgramID DCLProgramID of DCL program to release. 


DESCRIPTION 

FWRel easeDCLProgram releases the resources allocated for a DCL program. 
FWRel easeDCLProgram will call the release proc set for the given DCL program 
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with FWSetDCLProgramRel easeProc. If no translation has been performed on the 
DCL program, FWRel easeDCLProgram will typically call a routine in the FWIM to 
release its internal resources allocated for the DCL program. If translation has 
been performed on the DCL program, FWRel easeDCLProgram will typically call a 
routine in the FireWire services, which will release its internal resources 
allocated for the DCL program and call FWRel easeDCLProgram on the translated 
DCL program. This second call to FWRel easeDCLProgram will typically call into 
the FWIM. 


9.4.15 FWCallDCLCallProc 

FWCal 1 DCLCal 1 Proc calls the procedure specified for a DCLCal 1 Proc command. 


OSStatus FWCallDCLCallProc ( 

DCLProgramID delProgramID, 

DCLCal1ProcPtr pDCLCal1Proc); 


delProgramID 
pDCLCal1Proc 


DCLProgramID of DCL program to start. 
DCLCal 1 Proc to call. 


DESCRIPTION 

FWCal 1 DCLCal 1 Proc calls the procedure specified for the given DCLCal 1 Proc 
command. Typically, a FWIM will call FWCal 1 DCLCal 1 Proc when it executes a 
DCLCal 1 Proc command. FWIMs should use FWCal 1 DCLCal 1 Proc instead of 
directly calling the procedure specified for the DCLCal 1 Proc command as there 
may be some additional setup required by the FireWire services before calling 
the DCLCal 1 Proc procedure. 


9.5 DCL Commands 


9.5.1 kDCLSendPacketStartOp 

The kDCLSendPacketStartOp command is used to specify the first part of a 
packet to be sent to a data stream. It uses the DCLTransferPacket record. 
Subsequent parts of the packet may be specified by using the kDCLSendPacketOp. 
Packets are defined as a contiguous string of DCL packet commands that start 
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with a DCL packet start command and end with any DCL command that is not 
a DCL packet command (e.g., a string of DCL commands such as 
kDCLSendPacketStartOp, kDCLSendPacketOp, kDCLSendPacketStartOp, 
kDCLSendPacketStartOp, kDCLSendPacketOp, kDCLCal 1 ProcOp, kDCLSendStartOp, 
kDCLCal 1 ProcOp, will send 4 packets). Thus, scatter/gather lists may be used in 
constructing packets. To determine the total size of a packet, a DCL compiler 
(FWIM) should sum the size fields of all the DCL packet start and packet 
commands defining the packet. DCL send packet buffers do not include the 
packet header. The packet header is constructed by the compiler based upon 
the isochronous channel number for the data stream associated with the DCL 
program, the tag and sync bits specified by a kDCLSetTagSyncBi tsOp command, 
and the computed length of the packet. 


9.5.2 kDCLSendPacketWithHeaderStartOp 

The kDCLSendPacketWi thHeaderStartOp command is similar to 
kDCLSendPacketStartOp except that it specifies that the packet buffers will 
contain the packet header in the first quadlet of the packet buffers. The 
kDCLSendPacketWi thHeaderStartOp command uses kDCLSendPacketOp commands 
to specify additional parts of the packet. 


9.5.3 kDCLSendPacketOp 

The kDCLSendPacketOp command is used to specify part of a packet to be sent to 
a data stream. It must always come immediately after a kDCLSendPacketStartOp 
or kDCLSendPacketOp command. It uses the DCLTransferPacket record. 


9.5.4 kDCLSendBufferOp 

The kDCLSendBufferOp command is used to specify a buffer of continuous data 
to be sent to a data stream. It uses the DCLTransferBuffer record. The 
kDCLSendBufferOp command is different from the kDCLSendPacketStartOp and 
kDCLSendPacketOp commands in that it transmits multiple packets from one 
buffer. Transmitted packets are read from the kDCLTransmi tBufferOp buffer until 
the buffer is emptied. 

The size of the transmitted packets is set by the kDCLSetPacketSi zeOp command. 
If the remaining amount of buffer space in a kDCLSendBufferOp buffer is smaller 
than the specified packet size, the rest of the packet will be read from the next 
kDCLSendBufferOp buffer if there is one; otherwise, the packet length will be 
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shortened to the remaining amount of buffer space. If the next DCL send 
command is a send packet command, the packet length will be shortened to the 
remaining amount of buffer space. However, if non DCL transfer commands 
(e.g., DCL call proc command) come between two kDCLSendBufferOp 
commands, the rest of the packet will be read from the next kDCLSendBufferOp 
buffer. 

9.5.5 kDCLReceivePacketStartOp 

The kDCLRecei vePacketSta rtOp command is used to specify the first part of a 

scattered buffer to receive data from a data stream. It uses the 

DCLTransferPacket record. It is similar to the kDCLSendPacketStartOp for 

determining packet boundaries and total packet buffer sizes. If the packet 
received from the data stream is larger than the total buffer size for all the DCL 
packet start and packet commands for the packet, the end of the packet data 
will be lost. If the packet received from the data stream is smaller than the total 
buffer size, the additional buffer space will not be written to, and the next 
packet received will be placed in the next packet buffer that starts with the next 
DCL packet start command. The isochronous packet header is included as the 
first quadlet of data in the packet buffer. 


9.5.6 kDCLReceivePacketOp 

The kDCLRecei vePacketOp command is used to specify part of a scattered buffer 
to receive data from a data stream. It must always come immediately after a 

kDCLRecei vePacketSta rtOp or kDCLRecei vePacketOp command. It uses the 
DCLT ransferPacket record. 


9.5.7 kDCLReceiveBufferOp 

The kDCLReceiveBufferOp command is used to specify a buffer to receive 
continuous data from a data stream. It uses the DCLTransferBuffer record. The 
kDCLRecei veBuf ferOp command is different from the kDCLSendPacketSta rtOp and 
kDCLSendPacketOp commands in that it concatenates received packets into one 
buffer. Received packets are written into the kDCLRecei veBufferOp buffer until 
the buffer is filled. 

If only part of a packet fits into the remaining amount of buffer space, the rest 
of the packet will be placed into the next kDCLRecei veBufferOp buffer if there is 
one; otherwise, the rest of the packet data will be lost. If the next DCL receive 
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command is a packet receive command, the rest of the packet data will be lost. 
However, if non DCL transfer commands (e.g., DCL call proc command) come 
between two kDCLRecei veBufferOp commands, the rest of the packet data will 
not be lost and will be placed in the next kDCLRecei veBufferOp command. 


9.5.8 kDCLCallProcOp 

The kDCLCal 1 ProcOp command is typically used by a driver to be notified when 
a DCL program has reached a certain location. This is useful if a driver must 
regularly update buffers being sent to a data stream. This command uses the 
DCLCal 1 Proc record. The specified proc is called and passed a pointer to the 
DCLCal 1 Proc record. The procData field is typically set and used by the driver 
that created the DCL program and is not used by the DCL compiler. Latency 
issues prohibit guaranteeing when the kDCLCal 1 ProcOp's proc is called. 

Typically, a FWIM will set up a DMA program to generate an interrupt to 
service kDCLCal 1 ProcOp commands. The interrupt handler should call 
FWScheduleDeferredTask and then the FireWire deferred task should call 

FWCal 1 DCLCal 1 Proc. 


9.5.9 kDCLLabelOp 

The kDCLLabel Op command is used to specify a location in a DCL program that 
may be jumped to. This command uses the DCLLabel record. Some DMA 
architectures require a FWIM to know all of the locations in a DCL program 
that may be jumped to. 


9.5.10 kDCLJumpOp 

The kDCLJumpOp command is used to change the default command ordering of a 
DCL program. This command uses the DCLJump record. The kDCLJumpOp 
command may be used by a driver to create a looping DCL program. The 
pJumpDCLLabel field specifies the DCL label command to jump to. DCL jump 
commands may only jump to DCL label commands. 


9.5.11 kDCLSetTagSyncBitsOp 

The kDCLSetTagSyncBitsOp command is used to set the sync and tag bits for 
packets being sent to a data stream. This command uses the DCLSetTagSyncBits 
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record. It sets the tag and sync bits for all subsequent packets following the 
DCL program execution links (i.e., following DCL jump command links) until 
the next kDCLSetTagSyncBi tsOp command. 

The tagBi ts field of the DCLSetTagSyncBi ts record has only 2 significant bits 
(lower order 2 bits), and the syncBi ts field has only 4 significant bits (lower 
order 4 bits). 


9.5.12. kDCLUpdateDCLListOp 

The kDCLUpdateDCLListOp command is used to specify a list of DCL commands 
that should be updated. A high level client will typically use this command just 
before or after a kDCLCal 1 ProcOp command. For example, a client using a DCL 
program to transmit data may set up a kDCLCal 1 ProcOp command to process 
new data for transmission. This client may set the next DCL command to be a 
kDCLUpdateDCLLi stOp command with a list of all of the DCL commands that 
need updating as a result of the new data processed in the call proc. 


9.5.13 kDCLTimeStampOp 

The kDCLTi meStampOp command is used to obtain a time stamp for a particular 
location within a DCL program. If a high level client wishes to know the cycle 
that a particular packet was transmitted, it may place a kDC LTi meStampOp 
command immediately after the transmit packet command. The DCL program 
compiler should fill in the time stamp value with the current cycle timer after 
the packet has been transmitted. 

Note that in most cases, the best accuracy for the time stamp value is within 
one cycle number; a high level client should not assume that the time stamp 
value is accurate within the cycle offset field. In some cases during high bus 
traffic, the time stamp value may be off by one cycle. Some DCL compilers may 
have to account for time stamp lags caused by transmit FIFOs. 
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9.6 DCL Command Flags 


9.6.1 kFWDCLOpDynamicFlag 

The kFWDCLOpDynami cFl ag indicates that the given DCL command may be 
modified during execution of the DCL program. This flag must be set for all 
DCL commands that a high level client wishes to modify during DCL program 
execution. This flag is used by DCL compilers to allocate any extra resources 
that may be needed when the DCL command is modified. 


9.6.2 kFWDCLOpVendorDefinedFlag 

The kFWDCLOpVendorDef i nedFl ag indicates that the given command is one 
specific to the DCL compiler. This flag may sometimes be used by FWIMs to 
take advantage of special purpose hardware in the host controller. A high level 
client may take advantage of the special purpose hardware if it is aware of the 
host controller it is using and the vendor defined DCL commands supported 
by the host controller's FWIM. 

A FWIM may indicate that it supports some vendor defined DCL commands 
by creating some property in its Name Registry entry. A high level client 
wishing to use these commands may search the Name Registry to find the 
Name Registry entry of the host controller it is using. The high level client may 
do this by starting its search at its own Name Registry entry and searching its 
parents until it finds an entry with a FWIM (the entry will have a driver 
descriptor property with a service category of ’ fwi m ’). The high level client can 
then check for the vendor defined DCL property in the found Name Registry 
entry. 
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This chapter describes the services that the Mac OS provides to access CSR 
configuration ROMs. 


10.1 Structures, Data Types, and Constants 


10.1.1 CSRROMSearchCriteria 


csrROMSearchType; 
keyType; 
key Hi , 
keyLo; 

CSRROMSearchCriteria 
*CSRROMSearchCriteriaPtr; 

csrROMSearchType Type of search criteria record. 

keyType Types of keys to search for, in any combination. 

See "10.1.4 CSR Constants" (page 208). 
key H i, key Lo Key values to search for. Each key value is 

represented by a bit position in key Hi or 
key Lo. Can be be any combination of values. 


struct CSRROMSearchCri ten aStruct 
{ 

UInt32 

UInt32 

UInt32 

); 

typedef struct CSRROMSearchCriteriaStruct 
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10.1.2 CSRROMUniquelD 


struct CSRROMUniquelDStruct 
{ 

UInt32 hi , 

1 o; 

) 

typedef struct CSRROMUniquelDStruct CSRROMUniquelD, 

*CSRROMUniquelDPtr; 

hi, 1 o Most significant and least significant values of 64-bit 

unique ID. 


10.1.3 CSR Types 


typedef UInt32 
typedef UInt32 
typedef Kernel ID 


CSRROMEntry Iterator; 
CSRROMIterationOp; 
CSRROMEntryID; 


CSRROMEntryIterator 

CSRROMIterationOp 


CSRROMEntryID 


Reference used to maintain 
state of an iterated search. 

The iteration op specifies 

the direction of movement 
through an iterated search. 

Reference to a particular 
entry in the CSR 
configuration ROM. 


10.1.4 CSR Constants 


enum 


klnvalidCSRROMIterator = 0 

) ; 

klnval i dCSRROMIterator If an iterator value is equal to 

this constant, it is invalid. 
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enum 

f 

klnvalidCSRROMEntryID = 0 

}; 

klnval idCSRROMEntry ID If a configuration ROM entry ID is 

equal to this constant, it is invalid. 

enum 

i 


klterateContinue 

= 1 

klterateRoot 

= 2 

klterateParents 

= 3 

klterateChi1dren 

= 4 

klterateDescendants 

= 5 

klterateSibling 

= 6 


); 

klterateContinue 

klterateRoot 
klterateParents 
klterateChi1dren 
klterateDescendants 
klterateSibling 

enum 
i 

kCSRROMSearchForKey = 1 

}; 

kCSRROMSearchForKey Specifies a search for a particular 

key type and value. 

The following constants define the types of keys in the CSR 
configuration ROM: 

enum 

i 

kCSRImmediateKeyType = 0, 

kCSROffsetKeyType = 1, 


Continue iterating in previously 
specified direction. 

Start iterating from the root. 
Include all parents of entry. 
Include all children of entry. 
Include all descendants of entry. 
Include all siblings of entry. 
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kCSRLeafKeyType = 2, 

kCSRDirectoryKeyType = 3 


The following constants define the key type bits to use in the key Type field in 

the CSRROMSearchCri teri a record: 

enum 


kCSREverykeyType 
kCSRImmediatekeyTypeBit 
kCSROffsetKeyTypeBit 
kCSRLeafKeyTypeBit 
kCSRDirectorykeyTypeBi t 


= OxFFFFFFFF, 

= (1 << kCSRImmediatekeyType), 
= (1 << kCSROffsetkeyType), 

= (1 << kCSRLeafkeyType), 

= (1 << kCSRDirectorykeyType) 


The following constants define the standard CSR configuration ROM key 
values: 

enum 


kCSRTextualDescriptorkey 

= 0x01, 

kCSRBusDependent Infokey 

= 0x02, 

kCSRModuleVendorlDkey 

= 0x03, 

kCSRModuleHwVersionkey 

= 0x04, 

kCSRModuleSpecIdkey 

= 0x05, 

kCSRModuleSwVersionkey 

= 0x06, 

kCSRModuleDependent Infokey 

= 0x07, 

kCSRNodeVendorldkey 

= 0x08, 

kCSRNodeHwVersionkey 

= 0x09, 

kCSRNodeSpecIdkey 

= OxOA, 

kCSRNodeSwVersionkey 

= OxOB, 

kCSRNodeCapabi1itieskey 

= OxOC, 

kCSRNodeUniqueldkey 

= OxOD, 

kCSRNodeMemoryExtentkey 

= OxOE, 

kCSRNodeDependentlnfokey 

= 0x10, 

kCSRUnit Directorykey 

= 0x11, 

kCSRUnitSpecIdkey 

= 0x12, 

kCSRUnitSwVersionkey 

= 0x13, 

kCSRUnitDependent Infokey 

= 0x14, 
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kCSRUnitLocationKey = 0x15, 

kCSRUnitPol 1MaskKey = 0x16 


The following constants define the key value bits to use in the key Hi and key Lo 
fields in the CSRROMSearchCri teri a record: 


enum 


kCSREveryKey = OxFFFFFFFF, 

kCSRTextualDescriptorKeyHiBit = 0, 

kCSRTextualDescriptorKeyLoBit = (1 << kCSRTextualDescriptorKey), 

kCSRBusDependentInfoKeyHiBit = 0, 

kCSRBusDependentlnfoKeyLoBit = (1 << kCSRBusDependentlnfoKey), 

kCSRModuleVendorIDKeyHiBit = 0, 

kCSRModuleVendorIDKeyLoBit = (1 << kCSRModuleVendorIDKey), 

kCSRModuleHwVersionKeyHiBit = 0, 

kCSRModuleHwVersionKeyLoBit = (1 << kCSRModuleHwVersionKey), 

kCSRModuleSpecIdKeyHiBit = 0, 

kCSRModuleSpecIdKeyLoBit = (1 << kCSRModuleSpecIdKey), 

kCSRModuleSwVersionKeyHiBit = 0, 

kCSRModuleSwVersionKeyLoBit = (1 << kCSRModuleSwVersionKey), 

kCSRModuleDependentInfoKeyHiBit = 0, 

kCSRModuleDependentlnfoKeyLoBit = (1 << kCSRModuleDependentlnfoKey), 
kCSRNodeVendorldKeyHiBit = 0, 

kCSRNodeVendorldKeyLoBit = (1 << kCSRNodeVendorldKey), 

kCSRNodeHwVersionKeyHiBit = 0, 

kCSRNodeHwVersionKeyLoBit = (1 << kCSRNodeHwVersionKey), 

kCSRNodeSpecIdKeyHiBit = 0, 

kCSRNodeSpecIdKeyLoBit = (1 << kCSRNodeSpecIdKey), 

kCSRNodeSwVersionKeyHiBit = 0, 

kCSRNodeSwVersionKeyLoBit = (1 << kCSRNodeSwVersionKey), 

kCSRNodeCapabi1itiesKeyHiBit = 0, 

kCSRNodeCapabi1itiesKeyLoBit = (1 << kCSRNodeCapabi1itiesKey), 

kCSRNodeUniqueldKeyHiBit = 0, 

kCSRNodeUniqueldKeyLoBit = (1 << kCSRNodeUniqueldKey), 

kCSRNodeMemoryExtentKeyHiBit = 0, 

kCSRNodeMemoryExtentKeyLoBit = (1 << kCSRNodeMemoryExtentKey), 

kCSRNodeDependentInfoKeyHiBit = 0, 

kCSRNodeDependentlnfoKeyLoBit = (1 << kCSRNodeDependentlnfoKey), 

kCSRUnitDirectoryKeyHiBit = 0 
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kCSRUnitDirectoryKeyLoBi t 
kCSRUnitSpecIdKeyHiBi t 
kCSRUnitSpecIdKeyLoBi t 
kCSRUni tSwVersionKeyHiBit 
kCSRUnitSwVersionKeyLoBit 
kCSRUni tDependent InfoKeyHiBit 
kCSRUnitDependentlnfoKeyLoBit 
kCSRUni tLocationKeyHiBit 
kCSRUni tLocationKeyLoBit 
kCSRUni tPol 1 MaskKeyHiBit 
kCSRUnitPol 1 MaskKeyLoBit 


= (1 << kCSRUnitDirectoryKey), 

= 0 , 

= (1 << kCSRUnitSpecIdKey), 

= 0 , 

= (1 << kCSRUnitSwVersionKey), 

= 0 , 

= (1 << kCSRUnitDependentlnfoKey), 

= 0 , 

= (1 << kCSRUnitLocationKey), 

= 0 , 

= (1 << kCSRUnitPol1MaskKey) 


10.2 CSR Configuration ROM Search Routines 


The routines described in this section may be used with both local and remote 
devices. 


10.2.1 FWCSRROMCreatelterator 

FWCSRROMCreatelterator creates a CSR configuration ROM search iterator for 
use with the CSR configuration ROM search routines. 


OSStatus 

CSRR0MEntry Iterator 
FWReferencelD 


FWCSRROMCreatelterator ( 
*pCSRR0MIterator, 
fwReferencelD); 


<-- pCSRROMIterator Pointer to iterator used by the iterate 

and search routines. 

--> fwReferencel D Reference to device on which to search 

CSRconfiguration ROM. 


DESCRIPTION 

FWCSRROMCreatelterator creates a CSR configuration ROM search iterator for 
the FireWire device referenced by fwReferencelD and returns it in 
pCSRROMIterator. The returned iterator is initialized to start searching at the 
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beginning of the CSR configuration ROM root directory with a direction of 
klterateDescendants. This setting causes the iterator to search the entire CSR 
configuration ROM of the referenced device. 


10.2.2 FWCSRROMDisposelterator 

FWCSRROMDi sposelterator disposes of the iteration structure after searching is 
finished. 

OSStatus FWCSRROMDisposelterator ( 

CSRROMEntryIterator csrROMIterator); 

--> csrROMEntry Iterator Iterator to dispose. 


DESCRIPTION 

FWCSRROMDi sposelterator deallocates the memory allocated for the given CSR 
configuration ROM search iterator. 


10.2.3 FWCSRROMSetlterator 

FWCSRROMSetlterator sets a given iterator to start at a given CSR ROM directory 
entry using a given search direction. 


OSStatus FWCSRROMSetlterator 

CSRROMEntryIterator 
CSRROMEntryID 
CSRROMIterationOp 

--> csrROMIterator 
--> csrROMEntry ID 

--> relationship 


( 

csrROMIterator, 
csrROMEntrylD, 
relationship); 

Iterator to set. 

Reference to directory entry to start 
searching from. 

Direction to search. 


DESCRIPTION 

FWCSRROMSetlterator sets the given iterator to start searching from the CSR 
ROM directory entry specified by csrROMEntry ID in the direction specified by 
relationship. If csrROMEntrylD is invalid, the iterator continues searching from 
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its previous CSR ROM directory entry point. If rel ati onshi p is 
klterateContinue, the iterator continues searching in its previous direction. 


10.2.4 FWCSRROMEntrySearch 

FWCSRROMEntrySea rch retrieves the next CSR configuration ROM entry (and its 
value if desired) that matches the specified search criteria. 


OSStatus FWCSRROMEntrySearch ( 

CSRROMEntry Iterator csrROM Iterator, 

CSRROMIterationOp relationship, 


CSRROMEntryID 
Boolean 

CSRROMSearchCriteriaPtr 
Ptr 

UInt32 


*pCSRR0MEntryID, 
*pDone, 

pSearchCriteria , 
pEntryVal lie, 
*pEntrySize); 


--> csrROMEntrylterator 
--> relationship 
<-- pCSRROMEntryID 
<-- pDone 

--> pSearchCriteria 
<-- pEntryValue 
<--SpEntrySize 


Iterator used by iterate and search routines. 
Search direction. 

ID of next entry found. 

If true, searching has finished. 

Criteria to use for searching. 

Value of entry that was found. 

Size of above value. 


DESCRIPTION 

FWCSRROMEntrySea rch searches for a CSR ROM configuration entry that matches 
the given criteria and returns the entry ID that identifies that entry in 
pCSRROMEntry ID, or true in pDone if all matching entries have been found. 
FWCSRROMEntrySea rch optionally returns the value of that entry in pEntryVal ue if 
pEntryVal ue and p Entry Si ze are not nil. It copies as many bytes of the entry 
value as are specified in p Entry Si ze and returns in p Entry Si ze the number of 
bytes copied. 

FWCSRROMEntrySearch compares each entry against the criteria given in 

pSea rchCri teri a according to the csrROMSearchType in pSea rchCri teri a. 

If pCSRROMEntrylD is not ni 1, FWCSRROMEntrySearch returns a reference to the 
found entry in pCSRROMEntrylD. If pCSRROMEntrylD points to an entry equal to 
klnval idCSRROMEntryID, FWCSRROMEntrySearch calls FWCSRROMCreateEntrylD to 
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allocate a new entry ID and sets the newly created entry ID to reference the 
found entry; otherwise, FWCSRROMEntrySearch just sets the given entry ID to 
reference the found entry. In either case, when the caller of FWCSRROMEntrySearch 
is done with the entry ID, it must call FWCSRROMDi sposeEntrylD to free the 
memory allocated for the entry ID. 


10.3 CSR Configuration ROM Creation Routines 


The routines described in this section may only be used with the local device. 


10.3.1 FWCSRROMCreateEntry 

FWCSRROMCreateEntry creates a local CSR configuration ROM child entry within 
a given parent directory. 


OSStatusFWCSRROMCreateEntry ( 
CSRROMEntry ID 
CSRROMEntryID 
UInt32 
UInt32 
Ptr 

UInt32 


parentCSRROMEntrylD, 
*pCSRROMEntryID, 
entryType, 
entryKeyValue, 
pEntryData, 
entrySize); 


--> parentCSRROMEntrylD 
<-- pCSRROMEntrylD 
--> entryType 


--> entryKeyValue 

--> pEntryData 
--> entrySize 


ID of parent directory entry. 

Returned reference to newly created entry. 
Type of entry. Can be 

klmmediateCSRROMEntryType, 
kLeafCSRROMEntryType, or 
k DirectoryCSRROMEntryType. 

Key value of entry. Can be any of 64 
possible key values. 

New entry's data if entry is not a directory. 
Size of above entry. 


DESCRIPTION 

FWCSRROMCreateEntry creates a new local CSR configuration ROM directory 
entry within the given parent directory and returns a reference to the entry in 
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pCSRROMEntry ID. The returned entry ID can be used in subsequent calls to 
FWCSRROMCreateEntry or in calls to the other CSR ROM services. The newly 
created entry can be of any of the entry types as specified by entryType and any 
of the key values as specified by entryKeyVal ue. 

If the entry type is other than kCSRDi rectoryKeyType, the entry's data and size 
are specified by pEntryData and entrySi ze. FWCSRROMCreateEntry will allocate 
memory for the entry data and copy the data pointed to by pEntryData; thus, 
the caller may deallocate or alter the data pointed to by pEntryData after 
FWCSRROMCreateEntry returns. If the entry type is klmmedi ateCSRROMEntryType, 
pEntryData points to a 3-byte value and entrySi ze is 3. 

FWCSRROMCreateEntry builds up an internal tree structure representing the local 
configuration ROM. Newly created entries are added to this tree structure but 
are not instantiated within the local CSR configuration ROM until 
FWCSRROMInstanti ate is called. FWCSRROMInstanti ate converts the internal tree 
structure into the CSR configuration ROM format. It computes all of the leaf 
and directory offsets, lengths, and CRCs. Once it is done with the conversion, it 
initiates a bus reset. 

If pCSRROMEntrylD is not nil, FWCSRROMCreateEntry returns a reference to the 
newly created entry in pCSRROMEntrylD. If pCSRROMEntrylD points to an entry 
equal to klnval idCSRROMEntry ID, FWCSRROMCreateEntry calls 
FWCSRROMCreateEntry ID to allocate a new entry ID and sets the newly created 
entry ID to reference the newly created entry; otherwise, FWCSRROMCreateEntry 
just sets the given entry ID to reference the newly created entry. In either case, 
when the caller of FWCSRROMCreateEntry ID is done with the entry ID, it must call 
FWCSRROMDi sposeEntrylD to free the memory allocated for the entry ID. 


10.3.2 FWCSRROMDisposeEntry 

FWCSRROMDi sposeEntry disposes of a local CSR configuration ROM entry created 

by FWCSRROMCreateEntry. 

OSStatus FWCSRROMDisposeEntry ( 

CSRROMEntryID csrROMEntrylD); 

--> csrROMEntrylD Reference to entry to dispose. 
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DESCRIPTION 

FWCSRROMDi sposeEntry disposes of the local CSR configuration ROM entry 
referenced by csrROMEntryID. Memory for the entry will be deallocated and the 
entry will no longer appear in the local CSR configuration ROM. If the 
referenced entry is a directory entry, FWCSRROMDi sposeEntry will recursively 
dispose of all of the entries within the referenced directory entry. 

FWCSRROMDi sposeEntry will not dispose of csrROMEntryID; thus, the caller must 
still call FWCSRROMDi sposeEntrylD when it's done with csrROMEntryID. 


10.3.3 FWCSRROMInstantiate 

FWCSRROMI nstanti ate converts the tree structure representation of the local CSR 
configuration ROM into the CSR configuration ROM format and presents it to 
the FireWire bus by initiating a bus reset. 

OSStatus FWCSRROMInstantiate ( 

FWReferencelD fwReferencelD); 

--> fwReferencelD Reference to FireWire bus for which to 

instantiate CSR configuration ROM. 


DESCRIPTION 

FWCSRROMInstanti ate converts the internal CSR configuration ROM tree into the 
CSR configuration ROM format for the local node on the bus specified by 
fwReferencelD. FWCSRROMInstanti ate determines where to place all of the leaves 
and directories and computes the leaf and directory offsets, lengths, and CRCs. 
FWCSRROMInstanti ate initiates a bus reset to present the newly created CSR 
configuration ROM to the FireWire bus. 


10.4 CSR Configuration ROM Entry ID Routines 


The routines described in this section may be used with both local and remote 
devices. 


10.4 CSR Configuration ROM Entry ID Routines 
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10.4.1 FWCSRROMCreateEntrylD 

FWCSRROMCreateEntry ID creates a CSR configuration ROM entry ID for use with 
the CSR configuration ROM routines. 

CSRROMEntryID FWCSRROMCreateEntrylD (void); 


DESCRIPTION 

FWCSRROMCreateEntrylD creates a CSR configuration ROM entry ID for use with 
the CSR configuration ROM routines. FWCSRROMCreateEntrylD returns 
klnval i d CSRROMEntry ID if it cannot allocate memory for the ID. The ID returned 
by FWCSRROMCreateEntrylD will not reference any particular CSR configuration 
ROM entry and will be considered invalid by the CSR configuration ROM 
routines until it is filled with a valid entry reference; however, the CSR 
configuration ROM routines do not allocate a new entry ID when given an 
entry ID created by FWCSRROMCreateEntrylD. When the caller of 
FWCSRROMCreateEntrylD is done with the ID, it must call FWCSRROMDi sposeEntrylD 
to free the memory allocated for it. 


10.4.2 FWCSRROMDisposeEntrylD 

FWCSRROMDi sposeEntrylD frees the memory allocated for a given CSR 
configuration ROM entry ID. 

void FWCSRROMDisposeEntrylD ( 

CSRROMEntryID csrROMEntrylD); 

--> csrROMEntrylD CSR configuration ROM entry ID to dispose. 


DESCRIPTION 

FWCSRROMDi sposeEntrylD deallocates the memory allocated for the CSR 
configuration ROM entry ID specified by csrROMEntrylD. 


10.4.3 FWCSRROMCopyEntrylD 

FWCSRROMCopyEntry ID makes a copy of a CSR configuration ROM entry ID. 
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OSStatus FWCSRROMCopyEntrylD ( 

CSRROMEntryID srcCSRROMEntrylD, 

CSRROMEntryID *pDstCSRROMEntryID); 


--> srcCSRROMEntrylD CSR configuration ROM entry ID to copy from. 

<-- pDstCSRROMEntrylD CSR configuration ROM entry ID to copy to. 


DESCRIPTION 

FWCSRROMCopyEntrylD makes a copy of the CSR configuration ROM entry ID 
specified by srcCSRROMEntrylD and returns it in pDstCSRROMEntrylD. When this 
call is successful, the copied ID remains valid even if the source ID is 
invalidated or disposed of. If srcCSRROMEntrylD is equal to 
klnval i dCSRROMEntry ID or is an invalidated entry ID (i.e., does not reference a 
valid CSR configuration ROM entry), FWCSRROMCopyEntrylD will set 
pDstCSRROMEntrylD to point to an invalidated entry ID. 

If pDstCSRROMEntrylD points to an entry equal to klnval i dCSRROMEntry ID, 
FWCSRROMCopyEntrylD calls FWCSRROMCreateEntrylD to allocate a new entry ID 
and sets the newly created entry ID to reference the copied entry; otherwise, 
FWCSRROMCopyEntrylD just sets the given entry ID to reference the copied entry. 
In either case, when the caller of FWCSRROMCopyEntrylD is done with either entry 
ID, it must call FWCSRROMDi sposeEntrylD to free the memory allocated for the ID. 


10.4.4 FWCSRROMCompareEntrylDs 

FWCSRROMCompareEntrylDs compares two CSR configuration ROM entries. 


OSStatus FWCSRROMCompareEntrylDs ( 

CSRROMEntrylD 
CSRROMEntrylD 


csrROMEntryIDl 
csrROMEntryID2, 


Rnnl o a n 


--> csrROMEntryIDl 
--> csrROMEntryID2 
<-- pCSRROMEntryIDsEqual 


First CSR configuration ROM entry ID 
to compare. 

Second CSR configuration ROM entry 
ID to compare. 

Returned result of comparison. 
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DESCRIPTION 

FWCSRROMCompa reEntry I Ds compares the two given CSR configuration ROM 
entries for equality. If the two entry IDs reference the same CSR configuration 
ROM entry on the same device, FWCSRROMCompareEntryIDs will return true in 
pCS RROM Entry I Ds Equal . If the two entry IDs equal klnvalidCSRROMEntrylDor are 
invalidated entry IDs, FWCSRROMCompareEntryIDs will return true. Otherwise, 
FWCSRROMCompareEntryIDs will return fal se. If an entry ID is copied using 
FWCSRROMCopyEntry ID, comparing the source and destination entry IDs using 
FWCSRROMCompa reEntry I Ds will always return true. 


10.4.5 FWCSRROMInvalidateEntryIDType 

FWCSRROMInval idateEntryIDType invalidates a CSR configuration ROM entry ID 
without deallocating the entry ID. 

OSStatus FWCSRROMInvalidateEntryIDType ( 

CSRROMEntryID csrROMEntrylD); 

--> csrROMEntrylD CSR configuration ROM entry ID to 

invalidate. 


DESCRIPTION 

FWCSRROMInval i dateEntryIDType invalidates a given CSR configuration ROM 
entry ID. While FWCSRROMInval i dateEntryIDType may deallocate some memory 
used internally by the entry ID, it does not deallocate the memory used for the 
entry ID data structure. When the entry ID is invalidated, it no longer 
references a valid CSR configuration ROM entry, but it can still be used with 
the CSR configuration ROM routines and must still be disposed of with 
FWCSRROMDi sposeEntrylD when it is no longer needed. This routine is mainly 
used internally by the CSR configuration ROM services. 


10.4.6 FWCSRROMGetRootDirectory 

FWCSRROMGetRootDi rectory returns a CSR configuration ROM entry ID for the 
root directory of the referenced device. 

OSStatus FWCSRROMGetRootDirectory ( 

FWReferencelD fwReferencelD, 

CSRROMEntryID *pCSRR0MEntryID); 
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--> fwReferencelD Reference to device to get root 

directory of. 

<-- pCSRROMEntry ID Returned CSR configuration ROM root 

directory ID. 


DESCRIPTION 

FWCSRROMGetRootDi rectory returns a CSR configuration ROM entry ID for the 
root directory of the device referenced by fwReferencelD. 

If pCSRROMEntry ID points to an entry equal to klnval i dCSRROM Entry ID, 
FWCSRROMGetRootDi rectory calls FWCSRROMCreateEntrylD to allocate a new entry 
ID and sets the new ID to the root directory; otherwise, it just sets the given 
entry ID to reference the root directory. In either case, when the caller of 
FWCSRROMGetRootDi rectory is done with the ID, it must free the memory 
allocated for it by calling FWCSRROMDi sposeEntry ID. 


10.4.7 FWCSRROMGetEntryAddress 

FWCSRROMGetEntryAddress returns the 32-bit offset of a given CSR configuration 
ROM entry ID. 


OSStatus 


FWCSRROMGetEntryAddress ( 


CSRROMEntrylD 

UInt32 

--> csrROMEntryID 
<-- pAddress 


csrROMEntrylD, 

*pAddress); 

Reference to the CSR configuration 
ROM entry to get the address for. 
Returned address of the referenced 
CSR configuration ROM entry. 


DESCRIPTION 

FWCSRROMGetEntryAddress returns the address of the CSR configuration ROM 
entry referenced by csrROMEntrylD. 

The address returned in pAddress is a 32-bit offset from the 64-bit base address 
0 xnnnn FFFF 0000 0000, where nnnn is the node address. The address returned 
will therefore be OxFrrr rrrr, where rrr rrrr is the offset of the entry in the 
register space. 
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10.4.8 FWCSRROMGetEntryDataAddress 

FWCSRROMGetEntryDataAddress returns the 32-bit offset of data for a given CSR 
configuration ROM entry ID. 


OSStatus 


FWCSRROMGetEntryDataAddress ( 


CSRROMEntryID 
UIn 132 

--> csrROMEntrylD 
<-- pAddress 


csrROMEntrylD, 

*pAddress); 

Reference to the CSR configuration 

ROM entry to get the data address for. 
Returned address of the referenced 

CSR configuration ROM entry data. 


DESCRIPTION 

FWCSRROMGetEntryDataAddress returns the address of the CSR configuration 
ROM entry data referenced by csrROMEntrylD. If the CSR configuration ROM 
entry is an offset, leaf, or directory entry, FWCSRROMGetEntryDataAddress returns 
the base address of the entry's offset, leaf, or directory data. If the CSR 
configuration ROM entry is an immediate entry, FWCSRROMGetEntryDataAddress 
just returns the address of the entry itself, as does FWCSRROMGetEntryAddress. 

The address returned in pAddress is a 32-bit offset from the 64-bit base address 
0 xnnnn FFFF 0000 0000, where nnnn is the node address. The address returned 
will therefore be OxFrrr rrrr, where rrr rrrr is the offset of the entry in the 
register space. 
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This chapter describes the Mac OS FireWire services that support Function 
Control Protocol (FCP) commands. 


11.1 Structures, Data Types, and Constants 


11.1.1 FCP Services Types 


typedef void (FCPRespons 

FWCommandObjectlD 
Ptr 

UInt32 

typedef FCPResponseHandler 
FCPResponseHandler 
FCPResponseHandlerPtr 


eHandler) ( 

fwCommandObjectlD, 
responseBuffer, 
responseLength); 

*FCPResponseHandlerPtr; 

Routine that interprets response 
packets. 

Pointer to above routine. 


11.1.2 FCP Services Constants 


enum 


kResponseDoneStatus = 0, 
kResponseContinueStatus = 1, 
kResponseUnrecognizedStatus = 2 


11.1 Structures, Data Types, and Constants 
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kResponseDoneStatus 

kResponseContinueStatus 
kResponseUnrecognizedStatus 


Indicates that the received response 
completes the FCP transaction. 
Indicates that another response is coming. 
Indicates that the received response 
does not match the sent command. 


11.2 FCP Command Routines 


11.2.1 FWSendFCPCommand 

FWSendFCPCommand sends an FCP command onto the FireWire bus. 

OSStatus FWSendFCPCommand ( 

FWCommandObjectlD fwCommandObjectlD); 

--> fwCommandObj ectl D Command object controlling this service. 


DESCRIPTION 

FWSendFCPCommand attempts to send an FCP command to the device associated 
with the given fwReferencelD. This process consists of sending a write 
transaction for the commandBuffer to the device at address OxFFFF F000 0B00 
and waiting for a write request from the same device to the local node at 
address OxFFFF F000 0D00. 

The write request sent to the local node contains the response for the FCP 
command and is put in the buffer specified by responseBuffer. The maximum 
response size is specified by maxResponseLength and the actual response size is 
returned in responseLength. The maximum command and buffer sizes are 512 
bytes, so if the maxResponseLength value specified is 512 bytes or greater, the 
response returned in responseBuffer is guaranteed to be complete. 

FWSendFCPCommand waits for the amount of time specified by timeout for a 
response from the commanded device and retries the FCP command 

numRetri es times. 

When a response is received, FWSendFCPCommand calls the response packet 
handler passed in fcpResponseHandl er for each FCP command in the command 
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queue until a handler matches the response with a sent command. Each 
handler attempts to interpret the response and match it to the sent command. If 
the received response matches the sent command and indicates that the 
command is complete, the handler should return kResponseDoneStatus;in this 
case, FWSendFCPCommand will complete successfully. If the received response 
matches the sent command but the command is not complete, the handler 
should return kResponseConti nueStatus and can also reset the timeout period if 
desired; in this case, FWSendFCPCommand will wait for another response. If the 
received response does not match the sent command, the handler should 
return kResponseUnrecogni zedStatus; in this case, FWSendFCPCommand will call the 
handler for the next FCP command in the command queue. If no response 
packet handler recognizes the response packet, FWSendFCPCommand will ignore 
the response packet. 

It is the responsibility of each handler to copy the response data into the 
response buffer. If FWSendFCPCommand reaches a queued command with no 
handler, it assumes that the received response matches that command and 
copies the response data into the response buffer. 


11.2.2 FWAIIocateFCPCommandObject 

FWAl 1 ocateFCPCommandObject creates a command object that may be used to 
send FCP commands. 

OSStatus FWAIIocateFCPCommandObject ( 

FWCommandObjectID *pFWCommandObjectID); 

<-- pFWCommandObjectID Returned reference to created FCP 

FireWireservice command object. 


DESCRIPTION 

FWAl 1 ocateFCPCommandObject creates a FireWire service command object for the 
FCP class of FireWire services. In addition to the basic set of command object 
parameters, the command object created by FWAl 1 ocateFCPCommandObject will 
contain additional parameters specific to sending FCP commands. 

The basic set of parameters will default to the same values as in 
FWAl 1 ocateFWCommandObject. Most of the FCP specific parameters have no 
meaningful default values and must be explicitly set. The responseBuffer 
defaults to nil and the responseBufferSize defaults to 0; this indicates that 
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although a response packet must be received to successfully complete the 
FWSendFCPCommand routine, the contents of the response packet will be ignored 
and thrown away. The maxRetri es parameter will default to 0 meaning that no 
retries will be attempted. The transferFl ags parameter will default to 0. The 
fcpResponseHandler parameter will default to ni 1 meaning that any received 
response packet will be assumed to match the command sent with 
FWSendFCPCommand. 

The command object created by FWA11 ocateFCPCommandObject may be 
deallocated by FWDeal 1 ocateFWCommandObject. 


11.2.3 FWSetFCPCommandCommandBuffer 

FWSetFCPCommandCommandBuf fer sets the pointer to a buffer that contains the FCP 
command packet to be sent to a device. 


OSStatus FWSetFCPCommandCommandBuffer ( 

FWCommandObj ectlD fwCommandObj ectlD, 

Ptr commandBuffer); 


fwCommandObj ectlD 
commandBuffer 


Command object to set commandBuffer of. 
Pointer to buffer with FCP command. 


DESCRIPTION 

FWSetFCPCommandCommandBuffer specifies a buffer that contains the FCP 
command packet to be sent by the FWSendFCPCommand routine. 


11.2.4 FWGetFCPCommandCommandBuffer 

FWGetFCPCommandCommandBuf fer returns a pointer to the buffer that contains the 
FCP command packet to be sent to a device. 


OSStatus FWGetFCPCommandCommandBuffer ( 

FWCommandObj ectlD fwCommandObj ectlD, 

Ptr *pCommandBuffer); 


--> fwCommandObjectlD Command object to get commandBuffer of. 

<-- pCommandBuffer Returned pointer to buffer with FCP 

command. 


226 


11.2 FCP Command Routines 



CHAPTER 11 


Function Control Protocol Services 


DESCRIPTION 

FWGetFCPCommandCommandBuf fer returns the buffer that contains the FCP 
command packet to be sent by the FWSendFCPCommand routine. 


11.2.5 FWSetFCPCommandCommandLength 

FWSetFCPCommandCommandLength sets the size of the FCP command packet to be 
sent to a device 


OSStatus 

FWCommandObjectID 

UInt32 


FWSetFCPCommandCommandLength ( 
fwCommandObjectID, 
commandLength); 


--> fwCommandObjectID Command object to set commandLength of. 

--> commandLength Length of FCP command packet. 


DESCRIPTION 

FWSetFCPCommandCommandLength specifies the length of the FCP command packet 
to be sent to a device. Values greater than 512 bytes will be truncated to 512 
bytes. 


11.2.6 FWGetFCPCommandCommandLength 

FWGetFCPCommandCommandLength returns the size of the FCP command packet to 
be sent to a device. 


OSStatus FWGetFCPCommandCommandLength ( 

FwCommandObjectID fwCommandObjectID, 

UInt32 *pCommandLength); 


--> fwCommandObjectID 
<-- pCommandLength 


Command object to get commandLength of. 
Returned length of FCP command packet. 


DESCRIPTION 

FWGetFCPCommandCommandLength returns the length of the FCP command packet 
to be sent to a device. 
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11.2.7 FWSetFCPCommandResponseBuffer 

FWSetFCPCommandResponseBuffer sets the pointer to a buffer that will be filled 
with the FCP response packet sent by a device. 


OSStatus 


FWSetFCPCommandResponseBuffer ( 


FWCommandObj ectlD 
Ptr 


fwCommandObj ectlD, 
resposneBuffer); 


fwCommandObj ectlD 
responseBuffer 


Command object to set responseBuffer of. 
Pointer to buffer to fill with FCP 
response. 


DESCRIPTION 

FWSetFCPCommandResponseBuffer specifies a buffer that will be filled with the 
FCP response packet sent by the device that received the FCP command packet 
sent by the FWSendFCPCommand routine. 


11.2.8 FWGetFCPCommandResponseBuffer 

FWGetFCPCommandResponseBuffer returns a pointer to the buffer that will be filled 
with the FCP response packet sent by a device. 


OSStatus 


FWGetFCPCommandResponseBuffer ( 


FWCommandObj ectlD 
Ptr 


fwCommandObj ectlD, 
*pResponseBuffer); 


--> fwCommandObjectlD 
<-- pResponseBuffer 


Command object to get responseBuffer of. 
Returned pointer to buffer to fill with 
FCP response. 


DESCRIPTION 

FWGetFCPCommandResponseBuffer returns the buffer that will be filled with the 
FCP response packet sent by the device that received the FCP command packet 
sent by the FWSendFCPCommand routine. 
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11.2.9 FWSetFCPCommandResponseLength 

FWSetFCPCommandResponseLength sets the size of the FCP response packet 
received from a device. 


OSStatus FWSetFCPCommandResponseLength ( 

FWCommandObjectID fwCommandObjectID, 

UIn t3 2 responseLength); 


-> fwCommandObjectID 
-> responseLength 


Command object to set responseLength of. 
Length of FCP response packet. 


DESCRIPTION 

FWSetFCPCommandResponseLength specifies the length of the FCP response packet 
sent by the device that received the FCP command packet sent by the 
FWSendFCPCommand routine. Values greater than 512 bytes will be truncated to 
512 bytes. 

The value specified by the FWSetFCPCommandResponseLength routine is the actual 
length of the received response packet and not the size of the response buffer 
specified by FWSetFCPCommandResponseBuffer. FWSetFCPCommandResponseLength 
should only be called by a response packet handler routine when it determines 
that the response packet matches the command packet sent by 
FWSendFCPCommand. The response length set by the response packet handler 
should be the actual response length even if it is larger than the size of the 
response buffer. This enables the caller of FWSendFCPCommand to determine that 
the response packet was truncated. 


11.2.10 FWGetFCPCommandResponseLength 

FWGetFCPCommandResponseLength returns the size of the FCP response packet 
received from a device. 


OSStatus FWGetFCPCommandResponseLength ( 

FwCommandObjectID fwCommandObjectID, 

UInt32 *pResponseLength); 


--> fwCommandObjectID Command object to get responseLength of 

<-- pResponseLength Returned length of FCP response packet. 
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DESCRIPTION 

FWGetFCPCommandResponseLength returns the length of the FCP response packet 
sent by the device that received the FCP command packet sent by the 
FWSendFCPCommand routine. The response length is the actual length of the 
received packet and not the size of the response buffer specified by 
FWSetFCPCommandResponseBuf fer. If the received response packet's length is 
larger than the response buffer size, the response packet will be truncated to 
the response buffer's size, but the response length returned by 
FWGetFCPCommandResponseLength will indicate the actual size of the full response 
packet and will be larger than the response buffer size. 


11.2.11 FWSetFCPCommandResponseBufferSize 

FWSetFCPCommandResponseSi ze specifies the size of the buffer that will be filled 
with the FCP response packet sent by a device. 


OSStatus FWSetFCPCommandResponseBufferSize ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 responseBufferSize); 


--> fwCommandObjectlD Command object for responseBufferSize. 

--> responseBuf ferSi ze Size of response buffer. 


DESCRIPTION 

FWSetFCPCommandResponseBufferSi ze specifies the size of the buffer that will be 
filled with the FCP response packet sent by the device that received the FCP 
command packet sent by the FWSendFCPCommand routine. If the specified size is 
not large enough for a received response packet, the response packet will be 
truncated to the size of the buffer. If the specified size is 512 bytes or greater, all 
response packets will be guaranteed to fit in the response buffer without being 
truncated. 


11.2.12 FWGetFCPCommandResponseBufferSize 

FWGetFCPCommandResponseBufferSi ze returns the size of the buffer that will be 
filled with the FCP response packet sent by a device. 
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OSStatus FWGetFCPCommandResponseBufferSize ( 

FWCommandObjectID fwCommandObjectID, 

UInt32 *pResponseBufferSize); 


--> fwCommandObjectlD Command object to get responseLength of. 

<-- pResponseBuf ferSi ze Returned size of response buffer. 


DESCRIPTION 

FWGetFCPCommandResponseBuf ferSi ze returns the size of the buffer that will be 
filled with the FCP response packet sent by the device that received the FCP 
command packet sent by the FWSendFCPCommand routine. 


11.2.13 FWSetFCPCommandTimeout 

FWSetFCPCommandTimeout sets the amount of time to wait before timing out on an 
FCP command packet sent with FWSendFCPCommand. 


dTimeout ( 

fwCommandObjectlD, 
timeout); 


OSStatus FWSetFCPComman 

FwCommandObjectlD 
Duration 

--> fwCommandObjectlD 
--> timeout 


Command object to set timeout of. 
Timeout period. 


DESCRIPTION 

FWSetFCPCommandT i meout specifies the amount of time to wait for an FCP 
response packet after sending an FCP command packet to a device. If the 
timeout period is exceeded and the maximum number of retries have been 
attempted, the FWSendFCPCommand service will complete with a status of 

ti meoutErr. 

Typically, the specification for the command transaction set being used will 
specify what the timeout period should be. Some command transaction sets 
(e.g., AV/C) specify one timeout for the initial response and a different timeout 
for subsequent responses to the same command. In this case, the response 
packet handler that matches a response packet indicating that more response 
packets are coming may call FWSetFCPCommandTimeout to set a new timeout 
period. In the case of AV/C, the initial timeout period is 100 ms, but if a busy 
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response packet is received, the timeout period for the final response packet is 
forever (durati onForever). Note, that if the response packet handler changes 
the timeout period, the timeout period should be reinitialized before the 
command object is reused with FWSendFCPCommand. 


11.2.14 FWGetFCPCommandTimeout 

FWGetFCPCommandTi meout returns the amount of time to wait before timing out 
on an FCP command packet sent with FWSendFCPCommand. 


ndTimeout ( 

fwCommandObj ectlD, 
*pTimeout); 


OSStatus FWGetFCPComma 

FWCommandObj ectlD 
Duration 

--> fwCommandObjectlD 
<-- pTimeout 


Command object to get timeout of. 
Returned timeout period. 


DESCRIPTION 

FWGetFCPCommandT i meout returns amount of time to wait for an FCP response 
packet after sending an FCP command packet to a device. 


11.2.15 FWSetFCPCommandMaxRetries 

FWSetFCPCommandMaxRetri es sets the maximum number of times that an FCP 
command packet should be resent after the timeout period has elapsed with no 
response. 


OSStatus FWSetFCPCommandMaxRetries ( 

FWCommandObj ectlD fwCommandObj ectlD, 

UInt32 maxRetries); 


--> fwCommandObjectl D Command object to set maxRetri es of. 

--> maxRetri es Maximum number of times to retry an F CP 

command. 
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DESCRIPTION 

FWSetFCPCommandMaxRetri es specifies the maximum number of times that 
FWSendFCPCommand should retry an FCP command that timed out. If 
FWSendFCPCommand retries an FCP command maxRetri es times with no response, 
it will complete with a status of ti meoutErr. If maxRetri es is 0 (the default), only 
one attempt will be made to send an FCP command. 


11.2.16 FWGetFCPCommandMaxRetries 

FWGetFCPCommandMaxRetri es returns the maximum number of times that an FCP 
command packet should be resent after the timeout period has elapsed with no 
response. 


OSStatus 


FWGetFCPCommandMaxRetries ( 


FWCommandObjectID 
UI n 13 2 


fwCommandObjectID, 
*pMaxRetries); 


--> fwCommandObjectID Command object to get maxRetri es of. 

<-- pMaxRetries Returned maximum number of times to retry 

an FCP command. 


DESCRIPTION 

FWGetFCPCommandMaxRetri es returns the maximum number of times that 
FWSendFCPCommand should retry an FCP command that timed out. 


11.2.17 FWSetFCPCommandTransferFlags 

FWSetFCPCommandTransferFl ags sets the flags to control the transfer of 
asynchronous packets used for FCP transactions. 


OSStatus FWSetFCPCommandTransferFlags ( 

FwCommandObjectID fwCommandObjectID, 

UInt32 transferFlags ); 


--> fwCommandObjectID Command object to set transferFl ags of. 

--> transferFlags Flags controlling the transfer of asynchronous 

packets used for FCP transactions. 
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DESCRIPTION 

FWSetFCPCommandTransferFl ags specifies the flags that control the transfer of 
asynchronous packets used for FCP transactions. These are the same flags used 
by the asynchronous packet transaction services. 

The kFWAsynchOverri deMaxPayl oad flag has no meaning for FCP commands 
because FCP packets are indivisible, and the target of an FCP command must 
be capable of receiving packets as large as the largest FCP command that the 
target supports. 


11.2.18 FWGetFCPCommandTransferFlags 

FWGetFCPCommandTransferFl ags returns the flags to control the transfer of 
asynchronous packets used for FCP transactions. 


OSStatus 


FWGetFCPCommandTransferFlags ( 


FWCommandObj ectlD 
UInt32 


fwCommandObj ectlD, 
*pT ransferFlags); 


--> fwCommandObj ectl D Command object to get transferFlags of. 

<-- pTransferFl ags Returned flags controlling the transfer 

of asynchronous packets used for FCP 
transactions. 


DESCRIPTION 

FWGetFCPCommandT ransferFl ags returns the flags that control the transfer of 
asynchronous packets used for FCP transactions. These are the same flags used 
by the asynchronous packet transaction services. 


11.2.19 FWSetFCPCommandResponseFlandler 

FWSetFCPCommandResponseHandl er sets the routine that will be called to interpret 
received FCP response packets. 

OSStatus FWSetFCPCommandResponseHandler ( 

FWCommandObj ectlD fwCommandObj ectlD, 

FCPResponseHandlerPtr fcpResponseHandler); 
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--> fwCommandObjectlD Command object to set responseHandt er of. 

--> fcpResponseHandl er Routine that interprets received FCP 

response packets. 


DESCRIPTION 

FWSetFCPCommandResponseHandl er specifies the routine that will be called to 
interpret received FCP response packets. This routine will be given a pointer to 
the received response packet, the response packet size, and the command 
object that was passed in to FWSendFCPCommand. 

The responsibility of the response handler is to compare the received FCP 
response packet with the FCP command packet specified in the command 
object given to the response handler. If the response handler determines that 
the response packet corresponds to the command packet, the response handler 
must indicate that fact and state whether the FCP transaction is complete or 
still pending. 

If the response handler determines that the FCP transaction is complete, the 
response handler should copy the response packet into the response buffer 
provided with the command object and return with a status of 
kResponseDoneStatus. If the response packet length is larger than the response 
buffer size, the response handler should truncate the response packet to fit 
within the response buffer. The response handler should also set the response 
length field of the command object to the actual length of the response packet. 

If the response handler determines that the FCP transaction is not complete, the 
response handler should just return kResponseContinueStatus. This will 
indicate that another FCP response packet is expected for the FCP command 
packet sent with the command object given to the response handler. The 
response handler may change the timeout period with FWSetFCPCommandTimeout 
to wait for a subsequent response packet. 

If the response handler determines that the received FCP response packet does 
not match the FCP command packet sent with the command object given to the 
response handler, the response handler should return 
kResponsellnrecogni zedStatus. This will indicate that the FireWire services 
should continue calling response handlers for any other outstanding FCP 
commands to find a matching FCP command. 

When an FCP response packet is received, the FireWire services will scan the 
FireWire service command queue for outstanding FCP commands. For each 
queued FCP command running in the order that they were issued, the FireWire 
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services will call the response handler set in the command object of the queued 
FCP command and pass it the command object of the queued FCP command, a 
pointer to the received response packet, and the response packet length. The 
FireWire services will continue calling the response handlers until a response 
handler returns a status other than kResponseUnrecogni zedStatus or until the 
response handlers for all queued FCP commands have been called. If no 
response handler recognizes the received response packet, the packet will be 
ignored. 

If a response handler is not specified for a command object, a default handler 
will be used that will always return kResponseDoneStatus and will copy the 
received response packet into the response buffer. 


11.2.20 FWGetFCPCommandResponseHandler 

FWGetFCPCommandResponseHandl er returns the routine that will be called to 
interpret received FCP response packets. 


OSStatus FWGetFCPCommandTransferFlags ( 

FWCommandObj ectlD fwCommandObj ectlD, 

FCPResponseFlandlerPtr *pFCPResponsehlandler); 


--> fwCommandObj ectl D Command object to get responseFIandler of. 

<-- pFCPResponseFlandler Returned routine that interprets received 

FCP response packets. 


DESCRIPTION 

FWGetFCPCommandResponseFlandl er returns the routine that will be called to 
interpret received FCP response packets. 


11.2.21 FWSetFCPCommandParams 

FWSetFCPCommandPa rams sets all of the parameters that are used for the FCP 
FireWire service commands. 

OSStatus FWSetFCPCommandParams ( 

FWCommandObj ectlD fwCommandObj ectlD, 

Ptr commandBuffer, 

UInt32 commandLength, 
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Ptr 

UI n 13 2 
Duration 
UI n 13 2 
UI n 13 2 

FCPResponseHandlerPtr 


responseBuffer, 
responseBufferSize, 
timeout, 
maxRetries, 
transferFlags, 
fcpResponseHandler); 


--> fwCommandObjectlD 
--> commandBuffer 
--> commandLength 
--> responseBuffer 
--> responseBufferSize 
--> timeout 
--> maxRetries 

--> transferFlags 

--> fcpResponseHandler 


Command object to set parameters of. 

Pointer to buffer with FCP command. 

Length of FCP command packet. 

Pointer to buffer to fill with FCP response. 

Size of response buffer. 

Timeout period. 

Maximum number of times to retry an FCP 
command. 

Flags controlling the transfer of asynchronous 
packets used for FCP transactions. 

Routine that interprets received FCP 
response packets. 


DESCRIPTION 

FWSetFCPCommandParams sets all of the parameters that are used for the FCP 
FireWire service commands. This routine is provided for convenience to allow 
a driver to set all of the parameters with one procedure call. 


11.2.22 FWGetFCPCommandParams 

FWGetFCPCommandParams returns all of the parameters that are used for the FCP 
FireWire service commands. 


OSStatus 


FWGetFCPCommandParams ( 


FWCommandObjectID 

Ptr 

UI n 13 2 
Ptr 

UI n 13 2 
UI n 13 2 
Duration 


fwCommandObjectlD, 
*pCommandBuffer, 
*pCommandLength, 
*pResponseBuffer, 

*pResponseBufferSize, 
*pResponseLength, 

*pTimeout, 
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UInt32 

*pMaxRetries, 


UInt32 

*pTransferFl ags, 


FCPResponseHandlerPtr 

*pFCPResponseHandler); 

--> 

fwCommandObj ectlD 

Command object to get parameters of. 

<-- 

pCommandBuffer 

Returned pointer to buffer with FCP command. 

<-- 

pCommandLength 

Returned length of FCP command packet. 

<-- 

pResponseBuffer 

Returned pointer to buffer to fill with 

FCP response. 

<-- 

pResponseBufferSi ze 

Returned size of response buffer. 

<-- 

pResponseLength 

Returned length of FCP response packet. 

<-- 

pTimeout 

Returned timeout period. 

<-- 

pMaxRetries 

Returned maximum number of times to 
retry an FCP command. 

<-- 

pT ransferFlags 

Returned flags controlling the transfer 
of asynchronous packets used for FCP 
transactions. 

<-- 

pFCPResponseHandler 

Returned routine that interprets received 

FCP response packets. 


DESCRIPTION 

FWGetFCPCommandPa rams returns all of the parameters that are used for the FCP 
FireWire service commands. This routine is provided for convenience to allow 
a driver to get all of the parameters with one procedure call. In order to 
optimize this routine, FWGetFCPCommandParams assumes that all of the parameter 
pointers are valid and not nil. 
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This chapter describes miscellaneous services that the Mac OS provides for 
FireWire, including accessing the FireWire topology map, accessing node and 
device IDs, and resetting the FireWire bus. 


12.1 Structures, Data Types, and Constants 


12.1.1 Miscellaneous Services Types 


struct CSRNodeUniquelDStruct 
1 

UInt32 hi , 

1 o; 

}; 

typedef struct CSRNodeUniquelDStruct CSRNodeUniquelD, 

*CSRNodeUniqueIDPtr; 

hi , 1 o 64-bit unique node ID. 


12.1.2 FWTopologyMap 

The FireWire topology map structure is identical to the topology map structure 
outlined in IEEE Standard 1394, Section 8.3.2.4.1. 
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struct FWTopologyMapStruct 
f 

tint: 6 
UI n 116 
UInt32 
ij I nt 16 
UI n 116 
UInt32 

) ; 

typedef struct FWTopologyMapStruct 


1ength 
CRC 

generationNumber 

nodeCount 
selfIDCount 
selfIDs 


1ength ; 

CRC; 

generationNumber; 
nodeCount; 
selfIDCount; 
selfIDs[63*9]; 


FWTopologyMap, 

*FWTopologyMapPtr; 

Specifies the number of subsequent 
quadlets in the topology map. 

CRC-16 value covering all of the 
subsequent quadlets. 

Number of times the topology 
map has been generated. 

Number of nodes present on the bus 

Number of sel f ID packets stored. 

List of the first quadlets of all s e 1 f ID 
packets sent during the last bus 
reset. The sel f ID packets are 
ordered by their node ID values. 


12.2 Topology Information Routines 


12.2.1 FWGetTopologyMap 

FWGetTopol ogyMap returns the current topology map for the referenced FireWire 
bus. 

OSStatus FWGetTopologyMap ( 

FWReferencelD fwReferencelD 

FWTopologyMapPtr pFWTopologyMap); 
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--> fwReferencelD 
<-- pFWTopologyMap 


Reference to FireWire bus to get 
topology map for. 

Returned topology map. 


DESCRIPTION 

FWGetTopol ogyMap returns the current topology map of the bus referenced by 
fwReferencelD. The topology map will be placed in the buffer specified by 
pFWTopol ogyMap. This buffer must be large enough to hold the largest possible 
topology map. 

Because a bus reset can occur at any time, the returned topology map cannot be 
guaranteed to be up to date. 


12.2.2 FWGetNodelD 

FWGetNodelD returns the current node ID value and generation number for a 
given device. 


OSStatus FWGetNodelD ( 

FWReferencelD 
UInt32 
UInt32 


fwReferencelD, 

*pNodeID, 

*pGeneration Number); 


--> fwReferencelD 

<-- pNodelD 

<-- pGenerationNumber 


Reference to device to get node ID value 
and generation number for. 
Returned node ID. 

Returned generation number. 


DESCRIPTION 

FWGetNodelD returns the current node ID and generation number for the device 
referenced by fwReferencelD. Because a bus reset can occur at any time, the 
returned node ID value and generation number cannot be guaranteed to be up to 
date. 


12.2.3 FWGetUniquelD 

FWGetUniquelD returns the uniquelD value for a given device. 
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OSStatus FWGetUniquelD ( 

FWReferencelD fwReferencelD, 

CSRNodeUniquelDPtr pUniquelD); 

--> fwReferencelD Reference to device to get unqiue ID for. 

<-- pUniquelD Returned uniquelD. 


DESCRIPTION 

FWGetUniquelD returns the uniquelD value for the device referenced by 

fwReferencel D. 


12.2.4 FWGetLocalFWReferencelDFromFWReferencelD 

FWGetLocal FWReferencelDFromFWReferencelD returns a FireWire reference ID that 
references the local host node. 


OSStatus FWGetLocalFWReferencelDFromFWReferencelD ( 

FWReferencelD fwReferencelD, 

FWReferencelD *pLocalFWReferencelD); 


--> fwReferencelD Reference to bus to get local reference for. 

<-- pLocal FWReferencelD Reference to local host node. 


DESCRIPTION 

FWGetLocal FWReferencelDFromFWReferencelD returns a FireWire reference ID that 
references the local host node on the FireWire bus referenced by fwReferencelD. 
This local reference ID may be used with FWGetNodelD and FWGetUni quel D to get 
the node ID and unique ID for the local host node. The local reference ID may 
also be used with many of the other FireWire services that use reference IDs. 


12.2.5 FWGetFWDevicelDFromFWReferencelD 

FWGetFWDevi celDFromFWReferencelD returns a FireWire device ID that references 
the same device as another FireWire reference ID. 
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OSStatus FWGetFWDevicelDFromFWReferencelD ( 

FWReferencelD fwReferencelD, 

FWDevicelD *pFWDeviceID); 


--> fwReferencelD 
<-- pFWDevicelD 


Reference to device. 
Returned FireWire device ID 
referencing device. 


DESCRIPTION 

FWGetFWDevi celDFromFWReferencelD returns a FireWire device ID that references 
the same device as the given FireWire reference ID. This routine may be used to 
test if two FireWire reference IDs reference the same device. 


12.2.6 FWFindFWDeviceFromNodelD 

FWFi ndFWDevi ceFromNodelD returns a FireWire device ID that references a device 
with a given node ID. 


OSStatus 


FWFindFWDeviceFromNodelD ( 


FWReferencelD 
UI n 13 2 
UI n 13 2 
FWDevicelD 


fwReferencelD, 
generation, 
nodelD, 

*pFWDevicelD); 


--> fwReferencelD 
--> generation 
--> nodelD 
<-- pFWDevicelD 


Reference to bus to find device on. 
Generation value for which n ode ID is valid. 
Node ID of device to find. 

Returned FireWire device ID referencing 
device with given node ID. 


DESCRIPTION 

FWFi ndFWDevi ceFromNodelD returns a FireWire device ID that references the 
device with the given node ID. The fwReferencelD is used to reference the bus 
on which to find the device. If the generation value specified by generation is 
out of date with the current bus topology FWFi ndFWDevi ceFromNodelD will return 

busReconfiguredErr. 
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12.2.7 FWResetBus 

FWResetBus initiates a FireWire bus reset. 

OSStatus FWResetBus ( 

FWCommandObjectID fwCommandObjectlD); 

--> fwCommandObjectlD Command object controlling this service. 


DESCRIPTION 

FWResetBus initiates a FireWire bus reset on the bus referenced by the 
fwReferencel D parameter set for the given FireWire service command object. 
FWResetBus uses the basic FireWire service command object created by 

FWA11 ocateFWCommandObj ect. 
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This appendix describes the generic driver family services that the Mac OS 
provides for FireWire drivers. 


A.l Generic Driver Family Overview 


The generic driver family encompasses drivers of service category ' ndrv '. Most 
of the support for this driver type is provided by the Device Manager. The 
Generic Driver Family library is provided to facilitate hot swapping of devices 
controlled by generic drivers. The Generic Driver Family provides services for 
generic driver expert loaders to receive notification of generic driver events. 

Generic driver expert loaders may register for notification of the addition and 
removal of devices controlled by generic drivers. This notification is based 
upon the service type within the generic service category ' ndrv ’. Generic 
driver expert loaders specify which driver service types they are interested in 
and receive notification of events associated with drivers of those service types. 

Generic driver expert loaders may reside as extensions in the extensions folder. 
They must be a shared library with a file type of ' gdfx '. They must export a 
data symbol named TheGDFServi ceDescri pti on of type GDFServi ceDescri pti on. 
This data record specifies the name of the expert loader and the generic driver 
service types for which the expert loader is responsible for. When a driver of 
that service type is detected, the Generic Driver Family will load the expert if it 
isn't already loaded and call its entry point GDFExpertEntryPoi nt. Typically, the 
GDFExpertEntryPoi nt routine will register for notification for the service type 
the expert loader is responsible for. 

Generic driver expert loaders may reside in locations other than as extensions 
in the extensions folder, but their location must be provided to the Generic 
Driver Family using the expert registration routines detailed below. 


A.l Generic Driver Family Overview 
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A.2 Structures, Data Types, and Constants 


A.2.1 GDFServiceDescription 


struct GDFServiceTypeStruct 
{ 

OSType 
NumVersion 
OSType 

}; 

typedef struct GDFServiceType 


gdfServiceName; 
version; 
reserved; 

ruct GDFServiceType, 

*GDFServiceTypePtr; 


gdfServiceName 

version 
reserved 


Generic driver service type that expert is 
responsible for. 

Version of generic driver service. 

Set to 0. 


struct GDFServiceOSRunTimeStruct 
I 

GDFServiceOSRunTimeOptions 
Str31 
UIn 132 

); 

typedef struct GDFServiceOSRunTimeSt 


gdfServiceRuntime 
gdfServiceName 
gdfServiceDescReserved 

struct GDFServiceDescriptionStruct 
{ 

OSType 

GDFServiceDescVersiong 


gdfServiceRuntime; 
gdfServiceName; 
gdfServiceDescReserved[8]; 

ruct 

GDFServfceOSRunTime, 

*GDFServiceOSRunTimePtr; 

Generic driver service run time options. 
Text name of generic driver service. 

Set to zeros. 


gdfServiceDescSignature; 
dfServiceDescVersion; 


246 


A.2 Structures, Data Types, and Constants 



APPENDIX A 


Generic Driver Services 


GDFServiceType 
GDFServiceOSRunTime 


gdfServiceType; 
gdfServiceOSRuntime; 


typedef struct GDFServiceDescriptionStruct 

GDFServiceDescript ion, 
*GDFServiceDescriptionPtr; 


gdfServiceDescSignature 
gdfServiceDescVersion 
gdfServiceType 
gdfServiceOSRuntime 


Signature field of this structure. 

Version of this data structure. 

Description of generic driver service type. 
OS runtime requirements ofGDFService. 


A.2.2 GDFDeviceEventData 


struct GDFDeviceEventDataStruct 
i 

RegEntrylD 
DriverRefNum 
OSType 
UInt32 
GDFDevicelD 

GDFDeviceEventRegistrati on ID 
UInt32 


deviceRegEntrylD; 
driverRefNum; 
serviceType; 
deviceEvent; 
gdfDevicelD; 

gdfDeviceEventRegistrationID; 
eventHandlerData; 


typedef struct GDFDeviceEventDataStruct 

GDFDeviceEventData, 

*GDFDeviceEventDataPtr; 


deviceRegEntrylD 
driverRefNum 
serviceType 
deviceEvent 
gdfDevicelD 

gdfDeviceEventRegistrationID 
eventHandlerData 


Name Registry ID of device. 

Driver refnum for device. 

Generic driver service type for device. 
Type of event that occured. 

Generic Driver Family ID of device. 
Registration ID for this event. 

Data for use by the event handler. 
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A.2.3 Generic Driver Family Types 


typedef Kernel ID 
typedef Kernel ID 
typedef UInt32 
typedef UInt32 

typedef OSStatus (GDFExp 

typedef GDFExpertEntryPoint 


GDFDeviceEventRegistrationID; 
GDFDevicelD; 
GDFServiceDescVersion; 
GDFServiceOSRunTimeOptions; 

rtEntryPoint) (void) 

*GDFExpert EntryPointPtr; 


typedef OSStatus (GDFDeviceEventHandlerProc) ( 

GDFDeviceEventDataPtr pGDFDeviceEventData); 

typedef GDFDeviceEventHandlerProc *GDFDeviceEventHandlerProcPtr; 


GDFDeviceEventRegistrationID 

GDFDevicel D 
GDFServiceDescVersion 

GDFServiceOSRunTimeOptions 
GDFExpertEntryPoint 

GDFDeviceEventHandlerProc 


Reference to a generic driver expert 
event registration. 

Reference to a generic device driver. 

Version information for 

GDFServi ceDescri pti on. 

Runtime options for GDFServi ceDescri pti on. 

Entry point into a generic driver 
expert loader. 

Procedure to handle generic device events. 


A.2.4 Generic Driver Family Constants 


enum 


klnvalidGDFDeviceEventRegistrationlD = 0, 
klnvalidGDFDevicelD = 0 

); 

klnvalidGDFDeviceEventRegistrati on ID If a GDFDevi ceEventRegi strati on ID 

is equal to this constant, it is 
invalid. 

klnval i dGDFDevi cel D If a GDFDevi celD is equal to this 

constant, it is invalid. 
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enum 


kl rival i dGDFEvent 
kGDFDeviceAddedEvent 
kGDFDeviceRemovedEven t 


= 0 , 
= 1 , 
= 2 


klnvalidGDFEvent 
kGDFDeviceAddedEvent 

kGDFDeviceRemovedEvent 


An invalid generic driver event. 
Indicates that a generic driver 
device has been added. 
Indicates that a generic driver 
device has been removed. 


enum 


kGDFServiceDescriptionSignature = 'gdfs' 

); 


kGDFServiceDescriptionSignature Signature for a GDFServiceDescri pti 

record. 

enum 

{ 

klnitialGDFServiceDescriptor = 0 

1 ; 

klni ti al GDFServi ceDescri ptor Initial version of 

GDFServiceDescription record. 


enum 


kGDFServicelsLoadedUponDiscovery = (1 << 0) 

); 


kGDFServi celsLoadedUponDi scovery Indicates that the generic driver 

expert loader should be loaded 
immediately upon discovery. 


on 
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A.3 Generic Driver Family Routines 


A.3.1 GDFRegisterDeviceEventHandlerProc 

GDFRegi sterDevi ceEventHandl erProc registers a procedure to be called upon 
certain generic device events. 

OSStatus GDFRegisterDeviceEventHandlerProc ( 


OSType 
UIn 132 
UInt32 

GDFDeviceEventHandlerProcPtr 
UInt32 

GDFDeviceEventRegistrationID 

--> serviceType 

--> numEvents 

--> eventTable 

--> gdfDeviceEventHandl er 

--> eventHandlerData 

<-- pGDFDeviceEventRegistrationID 


serviceType, 
numEvents, 

*eventTable, 
gdfDeviceEventHandler, 
eventHandlerData , 
*pGDFDeviceEventRegistrationID); 

Generic driver service type to 
receive event notification for. 
Number of events in eventTabl e to 
receive event notification for. 

Table of events to receive 
notification for. 

Event handler procedure. 

Data for use by gdfDevi ceEventHandl er. 
Reference to this registration. 


DESCRIPTION 

GDFRegi sterDevi ceEventHandl erProc registers a procedure that will be called 
upon certain generic device events. When an event occurs for a generic device 
driver, notification is broadcast to all interested clients. Clients register the 
generic driver service type and the event types for which they wish to receive 
notification. 

Notification is sent to each client through the gdfDevi ceEventHandl er procedure. 
The Generic Driver Family passes in a GDFDevi ceEventData record, which gives 
the details of the event. When a new device is added, the Generic Driver 
Family will install the device driver into the unit table and send out a device 


250 


A.3 Generic Driver Family Routines 



APPENDIX A 


Generic Driver Services 


added event. When a device is removed, the Generic Driver Family will send 
out a device removed event. Once all connections to the removed device driver 
have been closed, the Generic Driver Family will remove the driver from the 
unit table and the device's entry from the Name Registry. 


A.3.2 GDFUnregisterDeviceEventHandlerProc 

GDFUnregi sterDevi ceEventHandl erProc unregisters a device event notification 
procedure registered with GDFRegi sterDevi ceEventHandl erProc. 

OSStatus GDFUnregisterDeviceEventHandlerProc ( 

GDFDeviceEventRegistrati on ID gdfDeviceEventRegistrationID); 

--> gdf Devi ceEventRegi strati on ID Reference to device event 

notification to unregister. 


DESCRIPTION 

GDFUnregi sterDevi ceEventHandl erProc unregisters a device event notification 
procedure registered with GDFRegi sterDevi ceEventHandl erProc. 


A.3.3 GDFRegisterFSSpecExpert 

GDFRegi sterFSSpecExpert registers the location of a generic driver expert 
residing within a file's data fork. 

OSStatus GDFRegisterFSSpecExpert ( 

FSSpecPtr pExpertFSSpec); 


--> pExpertFSSpec File spec location of generic driver 

expert loader. 


DESCRIPTION 

GDFRegisterFSSpecExpert registers the location of a generic driver expert loader 
residing in the data fork of the file specified by pExpertFSSpec. 

GDFRegi sterFSSpecExpert will extract the GDFServi ceDescri pti on record from 
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the expert file but will not immediately load the expert unless the 

kGDFServi cels Load edUponDiscovery flag is set. 


A.3.4 GDFRegisterFSSpecResourceExpert 

GDFRegi sterFSSpecResourceExpert registers the location of a generic driver 
expert loader residing within a file's resource fork. 


OSStatus 

FSSpecPtr 

ResType 

short 


GDFRegisterFSSpecResourceExpert ( 
pExpertFSSpec, 
expertResType, 
expertResID); 


--> pExpertFSSpec 
--> expertResType 
--> expertResID 


File spec location of generic driver 
expert loader. 

Resource type of resource that 
expert resides in. 

Resource ID of resource that expert 
resides in. 


DESCRIPTION 

GDFRegi sterFSSpecResourceExpert registers the location of a generic driver 
expert loader residing in the resource fork of the file specified by pExpertFSSpec 
and the resource specified by expertResType and expertResID. 

GDFRegi sterFSSpecResourceExpert will extract the GDFServi ceDescri pti on record 
from the expert resource but will not immediately load the expert unless the 
kGDFServi cels Load edUponDiscovery flag is set. 
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This appendix describes the services that the Mac OS component driver expert 
provides for FireWire drivers. 


B.l Component Driver Expert Overview 


The component driver expert is responsible for loading drivers of service 
category ' comp '. Most of the support for the component driver type is provided 
by the Component Manager. The component driver expert is provided to 
facilitate hot swapping of devices controlled by component drivers. For 
information about the Component Manager, see Inside Macintosh: More 
Macintosh Toolbox. 

Component drivers are drivers of service category ' comp '. They are 
implemented as standard Component Manager components with a few 
additions. First, they are created as extensions of file type ' ndrv ' and export a 
driver description record so they may be located by the driver loader library. 
Second, they must export a data structure called ThePluginDispatchTable that 
contains procedure pointers to an initialization routine, a finalization routine, 
and the main component interface routine. 

The component driver expert detects the addition and removal of devices 
controlled by component drivers. When a new device is added, the component 
driver expert will load the component driver code fragment and create a 
routine descriptor for the component's main interface routine. The component 
driver expert will then call the component driver to initialize itself. If 
initialization is successful, the component driver expert will register the 
component using the routine descriptor for the main interface routine and the 
driver description service type for the component subtype. 

When a device is removed and all open connections to the device's component 
driver have been closed, the component driver expert will unregister the 
component driver, call the component driver's finalize routine, and remove the 
component driver's code fragment. 


B.l Component Driver Expert Overview 
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B.2 Structures, Data Types, and Constants 


B.2.1 ComponentDriverPluginDispatchTable 


struct ComponentDriverPluginDispatchTableStruct 


UInt32 

ComponentDriverlnitializeProcPtr 
ComponentDriverFinalizeProcPtr 
ComponentRoutineProcPtr 


piuginVersion ; 

ComponentDriverlnitializeProc; 
ComponentDriverFinalizeProc; 
component InterfaceProcPtr; 


typedef struct ComponentDriverPluginDispatchTableStruct 

ComponentDriverPlugin DispatchTable, 
*ComponentDriverPlugin DispatchTablePtr; 


piuginVersion 

ComponentDriverlnitializeProc 
ComponentDriverFinalizeProc 
component InterfaceProcPtr 


Specifies the version of the dispatch table. 
Proc to initialize the component driver. 
Proc to finalize the component driver. 
Main interface into the component driver. 


B.2.2 Component Driver Types 


typedef pascal ComponentResul t (ComponentDriverlnitial izeProc) ( 

RegEntryIDPtr pRegEntryID); 

typedef ComponentDriverlnitializeProc *ComponentDriverlnitializeProcPtr; 


typedef pascal ComponentResult 
RegEntryIDPtr 

typedef ComponentDriverFinal izeProc 

ComponentDriverlniti al i zeProc 
ComponentDriverFi nal i zeProc 


(ComponentDriverFinal i zeProc) ( 
pRegEntryID); 

*ComponentDriverFinal i zeProcPtr; 

Proc to initialize the component driver. 
Proc to finalize the component driver. 
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B.2.3 Component Driver Constants 


enum 


kComponentDriverPluginVersion = 0x00010000 

); 

kComponentDri verPl ugi nVersi on Version of component driver plug-in 

dispatch table. 


B.3 New Component Driver Routines 


B.3.1 ComponentDriverlnitializeProc 

The ComponentDriverlnitializeProc procedure is used to initialize the 
component driver. 

typedef pascal ComponentResult (ComponentDriverlnitializeProc) ( 
RegEntryIDPtr pRegEntryID); 

--> pRegEntrylD Name Registry ID of device entry. 


DESCRIPTION 

The ComponentDri verlni ti al i zeProc procedure is used to initialize the 
component driver. It is called when a new device controlled by a component 
driver is added. A pointer to the Name Registry ID of the device that the 
component driver controls is provided to the ComponentDri verlni ti al i zeProc 
procedure. The component driver should perform whatever initialization is 
necessary. When the ComponentDri verlni ti al i zeProc command is given, the 
component has not been registered or opened. Thus, the component cannot call 
SetComponentlnstanceStorageto save any global data. Instead, the component 
should use CFM global storage to save any information from the 
ComponentDri verlni ti al i zeProc command. 
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B.3.2 ComponentDriverFinalizeProc 

The ComponentDri verFi nal f zeProc procedure is used to finalize the component 
driver. 

typedef pascal ComponentResult (ComponentDriverFinalizeProc) ( 

RegEntryIDPtr pRegEntryID); 

--> pRegEntrylD Name Registry ID of device entry. 


DESCRIPTION 

The ComponentDri verFi nal i zeProc procedure is used to finalize the component 
driver. It is called when a device controlled by a component driver is removed. 
A pointer to the Name Registry ID of the device that the component driver 
controls is provided to the ComponentDri verFi nal i zeProc procedure. The 
component driver should perform whatever deallocation is necessary. When 
the ComponentDri verFi nal i zeProc command is given, all open connections to 
the component have been closed, and the component has been unregistered 
with the Component Manager. 
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Table C-l lists the error codes specific to the FireWire support software. 
Additional Mac OS system errors are listed in the file errors . h. 


Table C-1 Error codes 


Name 

Packet values 

Value 

Description 

kFWAckBusyA 

4 


kFWAckBusyB 

5 


kFWAckBusyX 

3 


kFWAckComplete 

1 


kFWAckDataError 

13 


kFWAckPending 

2 


kFWAckTypeError 

14 


kFWResponseAddressError 

7 


kFWResponseComplete 

0 


kFWResponseConflictError 

4 


kFWResponseData Error 

5 


kFWResponseTypeError 

Function returns 

6 


noErr 

0 

No error 

accessErr 

-4167 

Requested access not allowed 

addressAlignmentErr 

-4172 

Address is not of proper alignment 

addressRangeErr 

-4171 

Address is not in range 
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Table C-1 Error codes (continued) 


Name 

Value 

alreadyRegistered Err 

-4168 

badSelfIDsErr 

-4188 

bus Reconfigured Err 

-4163 

channelActiveErr 

-4181 

channelNotAvai1ableErr 

-4184 

disconnectedErr 

-4169 

insufficientBandwidthErr 

-4164 

i n U s e E r r 

-4160 

invalidFWReferenceTypeErr 

-4186 

invalidIDErr 

-4165 

invalidIDTypeErr 

-4166 

invalidlsochPortIDErr 

-4185 

multipieTalkerErr 

-4180 

noChannelsAvailableErr 

-4183 

noListenerOrTalkerErr 

-4182 

notFoundErr 

-4161 

retryExceededErr 

-4170 

separateBusErr 

-4187 

timeoutErr 

-4162 


Description 

Item has already been registered 

Received self IDs are bad 

Bus was reconfigured 

Operation not permitted when 
channel is active 

Required channel was not available 

Target of request has been 
disconnected 

Not enough bandwidth was 
available 

Item already in use 

Operation does not support type 
of given reference ID 

Given ID is not valid 

Given ID is of an invalid type for 
the requested operation 

An isochronous port ID is invalid 

Tried to install multiple talkers 

No supported isochronous 
channels are available 

Every isochronous channel must 
have one talker and at least one 
listener 

Item not found 

Retry limit was exceeded 

Two or more entities are on two or 
more buses and cannot be 
associated with each other 

Something timed out 
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